dsh-session-import-codex

Readme

# dsh-session-import-codex

English | [中文](README.zh.md)

An out-of-tree DeepSeek Harness plugin and PowerShell-friendly CLI for importing Codex conversation history. It reads the official [Codex App Server](https://developers.openai.com/codex/app-server/) stable history methods, converts completed turns into validated Harness session events, persists them through the selected profile's public services, and creates or reuses workspaces from historical working directories.

The primary workflow is a one-shot CLI. The `/import-codex` chat command remains available for development and targeted fallback use.

## What the CLI imports

- all non-archived interactive Codex conversations returned by `thread/list` with `archived: false`;
- completed, interrupted, and failed turns that can be represented by the current converter;
- only reasoning summaries by default; raw reasoning content is never imported;
- sessions under deterministic ids such as `codex-<thread-id>`.

Active conversations are skipped. Existing destination ids never rewrite session logs; a durable rerun refreshes their cold projections and repeats idempotent workspace attachment. A malformed source is reported and does not stop the remaining batch.

The importer never reads Codex rollout files, desktop state, SQLite databases, or private JSONL files. It never writes Harness persistence files directly.

## Install from npm

Requirements:

- Node.js `^22.19` or `>=24`;
- pnpm 10;
- a working `codex` command on `PATH`;
- the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) CLI, either installed or run from its source checkout.

Install the npm package through Harness so the target profile dependency and bundle layer are updated together:

```powershell
dsh plugin --profile web add dsh-session-import-codex
```

When running Harness from source:

```powershell
$harnessPath = Read-Host 'Path to your DeepSeek Harness checkout'
Set-Location $harnessPath
pnpm dsh plugin --profile web add dsh-session-import-codex
```

No plugin checkout or consumer-side build is required. The npm tarball contains the compiled `lib/` files.

## Pair with dsh-llm-codex for a complete Codex migration

This importer moves your Codex **conversation history** into DSH. To also carry over your Codex **login and subscription**, pair it with [dsh-llm-codex](https://github.com/yequ172672/dsh-codex-subscription) (npm package `dsh-llm-codex`): a DSH LLM adapter plugin that reuses your local Codex CLI login (`~/.codex/auth.json`) and lets DSH keep using ChatGPT subscription models (such as `gpt-5.6-sol`) without an API key.

Install it the same way:

```powershell
dsh plugin --profile web add dsh-llm-codex
```

Both plugins build on the same `codex login` credential: this importer starts the Codex App Server to read history, while the adapter serves ChatGPT subscription models in DSH. Together they migrate your full Codex usage habit into DSH:

- conversation history and workspaces → this plugin;
- login credential, subscription models, and quota → `dsh-llm-codex`.

## Develop from source

Clone and build the plugin. The lockfile resolves development dependencies from the public npm registry; the Harness checkout does not need to be a sibling directory.

```powershell
git clone git@github.com:xing01l/session-import-codex.git
Set-Location session-import-codex
pnpm install --frozen-lockfile
pnpm build
$pluginPath = (Get-Location).Path
Set-Location $harnessPath
pnpm dsh plugin --profile web add $pluginPath
```

## Recommended PowerShell migration

The supported write workflow is offline because the profile stores do not expose a profile-wide writer lock:

1. Stop the target `dsh --profile web` process with `Ctrl+C`.
2. Run a dry run.
3. Run the real migration.
4. Restart the Web profile.

Run the profile-installed npm binary to validate every eligible conversation without writes:

```powershell
pnpm --dir "$env:USERPROFILE\.dsh\profiles\web" exec dsh-import-codex --profile web --dry-run
```

Perform the migration:

```powershell
pnpm --dir "$env:USERPROFILE\.dsh\profiles\web" exec dsh-import-codex --profile web
```

Restart Harness afterwards with `dsh --profile web`, or from its source checkout:

```powershell
Set-Location $harnessPath
pnpm dsh --profile web
```

The CLI prints complete counts and per-thread failure diagnostics in the terminal. A durable run creates or reuses one Harness workspace for each imported session whose historical `cwd` still exists, then attaches the session. It never creates missing directories.

### Run from a source checkout

```powershell
Set-Location $pluginPath
pnpm import:codex -- --profile web --dry-run
pnpm import:codex -- --profile web
```

For a short global development command, link the source checkout:

```powershell
pnpm --dir $pluginPath link --global
dsh-import-codex --profile web --dry-run
```

## CLI reference

```text
dsh-import-codex [--profile <name>] [--dry-run] [--json]
```

- `--profile <name>` selects the Harness profile; default: `web`.
- `--dry-run` validates source histories and destination collisions without session or workspace writes.
- `--json` suppresses human progress and emits one JSON document.
- `--help` prints usage.

Machine-readable validation example:

```powershell
pnpm import:codex -- --profile web --dry-run --json
```

Exit codes:

| Code | Meaning |
|---:|---|
| `0` | Batch completed without import or workspace failures. Existing destinations and active skips are expected outcomes. |
| `1` | Fatal composition, startup, App Server, or whole-batch failure. |
| `2` | Batch completed, but one or more conversations or workspace attachments failed. |
| `130` | Interrupted by the user with `Ctrl+C`. |

Rerunning the command is safe: deterministic destination ids prevent duplicate session creation, existing title projections are refreshed from their stored logs, and workspace attachment is idempotent.

## Chat-command fallback

These are Harness chat commands, not PowerShell commands:

```text
/import-codex <thread-id> --dry-run
/import-codex <thread-id>
/import-codex --all --dry-run
/import-codex --all
```

The command result appears as a compact row in the current chat. It persists imported sessions but does not switch the current chat to an imported session. Refresh the Web sidebar after a chat-command import.

## Architecture

The package remains an ordinary Harness bundle:

- `cordis.patch.yml` inserts the shared importer and chat-command plugin;
- the standalone launcher boots the selected profile's non-surface bundle layers;
- `cli.patch.yml` adds the startup and one-shot runner plugins;
- durable runs add `cli.workspace.patch.yml`, which composes the same public storage-domain, workspace, and session-projection-cache plugins used by the Web bundle;
- both adapters consume `ctx.codexSessionImport`;
- App Server processes use `ctx.subprocess`, sessions use `ctx.sessionPersistence`, and workspace changes use `ctx.workspaceRegistry`.

The launcher excludes the known Web and headless surface bundles, so the migration process does not start an HTTP server or an agent task.

## Configuration

The bundle row exposes these Cordis configuration fields:

| Field | Default | Purpose |
|---|---:|---|
| `codexCommand` | `codex` | Codex executable name or path. |
| `requestTimeoutMs` | `30000` | App Server request deadline. |
| `shutdownGraceMs` | `3000` | Graceful App Server termination window. |
| `maxDiagnosticBytes` | `65536` | Maximum captured process diagnostic bytes. |
| `listPageSize` | `100` | `thread/list` page size. |
| `reasoningPolicy` | `summary` | Import validated summaries or omit reasoning entirely. |

Override the `session-import-codex` row through the target profile's `cordis.patch.yml`; both the CLI and chat command consume the same resolved configuration.

## Troubleshooting

`profile "web" does not include dsh-session-import-codex` means the bundle is not installed in that profile. Run the `dsh plugin ... add` command above.

`codex` resolution or `initialize` failures mean the CLI cannot start a compatible Codex App Server. Confirm `codex --version` and `codex app-server --help` work in the same PowerShell session.

Exit code `2` is a completed partial migration. Read the `[import]` and `[workspace]` lines: import failures usually indicate unsupported history/schema data; workspace failures usually mean a historical `cwd` no longer exists.

If sessions imported with version 0.1.0 show the workspace basename instead of their Codex titles, update this plugin to 0.1.1 or newer, stop the Web profile, rerun the durable import command once, and restart Web. The rerun rebuilds title projections without rewriting conversation logs.

Do not run a write migration while the target Web/headless profile is still running. Stop it, rerun the CLI, then restart it.

## Development checks

```powershell
pnpm test
pnpm typecheck
pnpm lint
pnpm build
pnpm pack --dry-run
git diff --check
```

## Maintainer npm release

The package is published to the official npm registry even when the local install registry is a mirror. Confirm that the version is not already published, authenticate to npmjs, then publish; `prepublishOnly` runs tests, typecheck, and lint, while `prepack` rebuilds `lib/`.

```powershell
npm view dsh-session-import-codex versions --registry=https://registry.npmjs.org/
npm login --registry=https://registry.npmjs.org/
npm whoami --registry=https://registry.npmjs.org/
pnpm publish --access public --registry=https://registry.npmjs.org/
```

Do not publish until the matching Git commit is pushed to `https://github.com/xing01l/session-import-codex`.

## Contributing and security

See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md); do not attach conversation history or credentials to public issues.

## License

Released under the [MIT License](LICENSE).