dsh-codex-import
DeepSeek Harness 插件：将 Codex CLI/Desktop 对话导入为可恢复的 dsh-tui 会话。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:tzwkb/dsh-codex-import#64af420d8232a702ff394bcd217a3330c8cf8b1fCodex Import 以 dsh-codex-import 发布，当前版本为 0.3.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
A DeepSeek Harness plugin that imports Codex CLI/Desktop conversations into DSH as sessions dsh-tui can list, resume, and continue. Codex and DSH store conversations in unrelated formats, so neither tool can read the other's history.
Codex reasoning is encrypted server-side and cannot be decrypted; only its plaintext summaries survive, and those are imported.
rollout-*.jsonl or compressed rollout-*.jsonl.zst files; newer files may identify the segment with payload.id and the conversation root with the metadata lineage. The filename suffix is not the session id, and a paginated page names its page only in the filename — which is also accepted by --session.summary that becomes a reasoning block.<recommended_plugins>, <environment_context>, <permissions instructions>, IDE/application envelopes, # AGENTS.md instructions, …), while unwrapping the human section when an envelope contains ## My request for Codex:.codex_orphaned_tool placeholder, and a call without a flushed result gets a deterministic error result. Both remain resumable and are counted in the report.local_shell_call/shell_call records and correlates Codex completion events, so non-zero exits and failed MCP/patch calls remain visibly marked as tool errors.--session scan reads a bounded metadata prefix before deciding whether to read each body.From a clone of this repository:
dsh plugin --profile dsh-tui add "file:$PWD"
pnpm's file: protocol copies the package into the profile rather than symlinking it, so the installed copy is independent of the clone. The CLI appends the package to dsh.profile.bundles because it declares dsh.bundle.patch; nothing else needs configuring. Remove it with dsh plugin --profile dsh-tui remove dsh-codex-import.
Restart dsh-tui after installing — plugins mount at startup.
Inside a dsh-tui session:
/import-codex --list # see what is available before importing
/import-codex # lists too — nothing is written without a scope
/import-codex --since-hours 168 # conversations active in the last week
/import-codex --session <id> # one Codex session id (repeatable)
/import-codex --limit 10 # newest 10 after filtering
/import-codex --project /repo # this project and its descendants
/import-codex --archived # include archived Codex sessions
/import-codex --codex-root /backup/codex/sessions # alternate source
/import-codex --max-tool-output 4000 # smaller sessions, at the cost of detail
/import-codex --max-text-chars 65536 # per-text budget (default 262144; 0 disables)
/import-codex --full-history # replay everything; only fits one context if small
/import-codex --no-images # skip attachment admission
/import-codex --dry-run # convert and verify, write nothing
/import-codex --force # refresh even a session you continued in DSH
/import-codex --help
A bare invocation lists rather than importing everything in range, because the scope should be chosen deliberately. The list prints each conversation with its full session id, time span in local time, working directory, and opening prompt. --since-hours N selects conversations with activity in that window: one that started inside it, or one Codex is still appending to. Codex keeps a conversation open for days, so the file behind the chat you are in right now can carry a days-old name — the filename timestamp alone would hide it. Activity is proven by the timestamp of the newest record in the file, never by mtime alone, because the paginated rollout migration rewrites cold rollouts and gives a months-old file today's mtime. Every page of a selected conversation is imported: a page file holds only its own turns, so importing the live page by itself would truncate the session.
The same work is available from a shell, without a running harness:
node bin/import-codex.mjs list --since-hours 168
node bin/import-codex.mjs convert --since-hours 24 --out /tmp/import-check
node bin/import-codex.mjs sync --codex-root /backup/codex/sessions --dsh-home /tmp/dsh --dry-run
node bin/import-codex.mjs verify /tmp/import-check
node bin/import-codex.mjs audit ~/.dsh/sessions # read-only: what cannot be compacted
node bin/import-codex.mjs sync --since-hours 24 # into $DSH_TUI_SESSION_ROOT or $DSH_HOME/sessions
node bin/import-codex.mjs rollback --manifest /path/to/codex-import-manifests/<run>.json
convert writes a directory and stops there, so the result can be inspected first. sync is the same pipeline aimed at a live sessions root: convert to a scratch directory, verify, then reconcile session by session. --dry-run uses that same scratch-and-verify path and removes the scratch tree afterward; it does not open or mutate the attachment store. Both normal CLI commands open the attachment store directly, so they import images just as /import-codex does. --codex-root is useful for an archived export, and --dsh-home selects a profile's attachment home; an explicit --into or DSH_TUI_SESSION_ROOT takes precedence for the live sessions root.
Importing the same conversation again is safe, and cheap when nothing changed. Each session is compared against a fresh conversion by the digest of its event stream, which sorts every session into one of four outcomes:
| What happens | |
|---|---|
| Not imported yet | Installed. |
| Byte-identical content | Nothing is written at all. A re-run that changes nothing touches no file. |
| Content differs | Refreshed in place — same session id and directory, so /resume entries and workspace state stay valid. This is how a conversation that grew in Codex, or one imported before a converter change, is brought up to date. |
| Not the file this importer wrote | Left alone. |
The last case matters most. DSH appends one zstd frame per event batch, so a session you have continued inside DSH is no longer a two-frame log; rewriting it would delete your turns. A log at two frames whose digest does not match what the importer recorded is one something else rewrote, and is treated the same way. --force overrides this, and is destructive by design. A conversion that could not reach the attachment store is also refused rather than allowed to overwrite a log that holds images. A sync writes codex-import-state.json beside the sessions root; runs that install or refresh sessions also keep a run-specific JSON manifest under codex-import-manifests/. A no-op run preserves the previous manifest and its rollback history, while the text manifest remains only for older scripts.
An import run never deletes a session or imports one twice: a refresh replaces the file, keeping the directory, any sibling files, and the session id. The explicit rollback command is the one operation that removes a session created by that import.
A rollout is an append-only log, but Codex does not replay it: every compacted record replaces the history before it with the summary the record carries. Importing the whole rollout therefore imports history the model can no longer see, and a long conversation is easily hundreds of times larger than its own current window — one measured 464 MB rollout replays to about 8.24M tokens against a current Codex window of about 130k.
Size is not the whole problem. DSH condenses history by replaying the span being condensed to a summarizer, so once a history exceeds the model window:
The session lists, resumes, and then refuses every new turn — and manual compaction cannot rescue it. The default window import exists for that: the last compacted record plus every record after it, which is the context Codex itself still holds. Earlier snapshots are dropped because the last one summarised them. Conversation metadata (cwd, model, createdAt, title) is still read from the full record list, so a window never loses it.
--full-history keeps the old whole-replay behaviour for conversations that genuinely fit one context.
--max-text-chars N (default 262,144) is the second guard: a single oversized text is the one shape balanced compaction refuses to split and the tool-result pruner cannot touch. Text beyond the budget keeps its head and tail around [... N of M chars trimmed during Codex import ...], so nothing is lost silently.
--audit is read-only. It prices the model context of every installed session, names the ones above the advisory (~700k tokens), never rewrites, and never follows a symlink.
/import-codex --audit
node bin/import-codex.mjs audit ~/.dsh/sessions
The fix is to rebuild it from Codex, where the source conversation is intact:
/import-codex --session <codex session id> --force
node bin/import-codex.mjs sync --session <id> --force
--force is required because the installed log is no longer exactly what the importer wrote. It replaces that one session log; the Codex rollout is never modified. The session id and directory stay the same, so /resume and workspace state keep working. The rebuilt session should then appear on the clear side of the next --audit.
| Result | |
|---|---|
| Messages, tool calls and results | Imported in full, including readable item_completed telemetry messages when a normal item is missing. --max-tool-output N truncates each tool output to N chars if you need smaller sessions; the default is 0, which keeps everything. Missing calls/results are repaired with explicit placeholders and counted; non-zero exits remain marked as errors. |
| Reasoning | Only the plaintext summary, for roughly a third of records. The rest is a Fernet token keyed by OpenAI and cannot be read by any client. |
| Images | Imported through the attachment store, including App Server and telemetry-side user images plus structured image-generation results. Oversized or malformed inline base64 is rejected before allocation; valid image-store refusals are reported, and the transcript keeps an omission placeholder. |
| Codex-injected context | Dropped. The # Files mentioned by the user: envelope is unwrapped rather than dropped, because it wraps the human's actual prompt. |
| Compaction markers, world state, token counts, inter-agent envelopes | Dropped: context plumbing rather than conversation. Readable legacy agent_message text and messages that survive only inside a compaction's replacement_history are recovered. |
Codex tool names (exec, shell, …) | Preserved verbatim as history the model can read; they are not callable in DSH. |
An imported image is only visible again if the active model accepts images. A
catalog entry without inputModalities defaults to text-only, and the harness
then substitutes [image omitted because this model accepts text only; attachment sha256:…] before the request leaves the process — the import is
still correct, but the agent will say it cannot see images.
deepseek-flash and deepseek-v4-flash-vision-exp declare ["text","image"];
deepseek-v4-flash and deepseek-v4-pro do not. The acp profile is pinned to
deepseek-v4-flash, so verifying image playback through ACP yields a false
negative.
DSH validates a session log three times, and the weaker checks are not enough — an import can list, resume, and still fail the next turn. Five rules were each found by running a real check, and each is enforced by lib/verify.js:
surfaceOp marker.id.assistant/message needs numeric turn, numeric step, and a stream Array.tool-call content block on an assistant message — the provider reads tool_calls from the blocks, not from the tool/call event.docs/formats.md documents the full contract: the physical layout, the event mapping, the corpus-wide Codex record inventory, and why images and session ids must be handled the way they are.
dsh-tui profile installed$CODEX_HOME/sessions (default ~/.codex/sessions)Because the install is a copy, edits do not reach the harness on their own:
scripts/reinstall.sh # re-copies into the dsh-tui profile, then restart dsh-tui
scripts/reinstall.sh <profile> targets another profile. Re-running dsh plugin add refreshes an existing file: dependency in place; removing first is not required.
Tests use a synthetic Codex corpus and a throwaway DSH_HOME under .test-work, so they never read your personal history. Verification loads the lockfile-pinned DSH runtime into .test-runtime; no global DSH, ~/.dsh, or ~/.codex data is touched. The deterministic regression suite also covers malformed input, zstd magic collisions, bounded discovery, live-rollout window selection, dry-run side effects, rollback history, and symlink guards:
npm run test:setup # once per clone: download the isolated DSH test runtime
npm test # regressions, reconcile behaviour, slash command, and ACP resume smoke tests
node scripts/test-sync.mjs --keep # leave the scratch tree for inspection
GitHub Actions runs the same suite, syntax checks, and a publish-content audit on both Ubuntu and macOS, using the minimum supported Node 22.19 and the current Node 24 line, for every push to main and every pull request.
scripts/test-resume.mjs <sessions-root> [session-id] [dsh-home] hands one real session to the isolated acp profile to list and resume, which is how a specific conversion is proven loadable by the harness (DSH_HOME must be the home the profile resolves, or the list comes back empty):
DSH_HOME=/tmp/acp-home DSH_TUI_SESSION_ROOT=/tmp/acp-home/sessions \
node scripts/test-resume.mjs /tmp/acp-home/sessions
test-sync.mjs covers determinism, install, no-op re-sync, in-place refresh, both refusal cases, --force, and the image guard. test-plugin.mjs composes the plugin the way the harness does and invokes the handler, because the slash command is the surface that actually gets used and no other test reaches it.
Before changing lib/convert.js or lib/verify.js, read docs/formats.md. DSH_CODEX_IMPORT_SELFTEST=<path> makes the plugin record its command registration to a file, which is the only headless way to confirm the command registered — dsh-acp does not parse slash commands, and the acp profile does not load another profile's bundles.
MIT — see LICENSE.