feat(headless): add --session-id, --model, and --json for programmatic embedding

[icejean]

Summary

dsh --profile headless is the standard one-shot entry point, but it currently lacks three capabilities that are table stakes for embedding DSH as a programmatic backend (scripts, CI, service orchestration):

1. --session-id <id> — get-or-create session resume. Every headless invocation today creates a fresh randomUUID() session, so conversation state is lost across processes / restarts.
2. --model <provider>/<model> — per-run model override. The model is hard-coded in the profile (agent-default-model); callers must generate a temporary --patch file as a workaround.
3. --json — structured stdout (text / sessionId / provider / model / toolSummary / durationMs / stopReason / error), mirroring openclaw agent --json, instead of plain text that callers must regex-parse.

Motivation

openclaw agent --session-key/--session-id/--json, Claude Code, and Codex all support session resume, per-run model selection, and structured output. Headless has none of these, which forces embedders (e.g. our DataAI Portal, which drives dsh as an execution backend) to fork dsh-headless or write fragile regex / zstd-parsing workarounds.

The underlying capabilities already exist — AgentRegistry.resume({ resumeSessionId }), session-persistence-jsonl, and the runner's agent.session.events stream — so these flags are really just the headless entry point wiring them up.

Proposed changes (all in packages/bundle/headless/)

• src/startup.ts — parse --session-id, --model, --json
• src/index.ts (runner) — get-or-create resume branch + model override + structured result summary
• cordis.patch.yml — wire the new fields from the startup provider into the runner config

Semantics

• No flag → behavior unchanged (backward compatible).
• --session-id <id> — resume the persisted session with this id when it exists, otherwise create it (get-or-create). Backed by the existing AgentRegistry.resume() + session-persistence-jsonl.
• --model <provider>/<model> — override agent-default-model for this run. Omitting the provider keeps the current one.
• --json — single-line JSON object on stdout; exit-code semantics unchanged (0 on completed, non-zero otherwise); stopReason === "error" carries an error object.

Status

--session-id has been implemented in a local fork and verified end-to-end (cross-process resume of pure conversation history — not long-term memory — confirmed via the persisted session JSONL). --model and --json are designed but not yet implemented upstream.

Posting here first to align on scope and API naming before writing the final code. Happy to open a PR once there's agreement — detailed per-flag design notes are available if useful.

[denial123789]

Strong +1 on making the headless boundary explicit. A few contract details would make this safer for CI and service orchestration:

1. In --json mode, reserve stdout for exactly one machine-readable result and send every diagnostic/progress line to stderr. Add a small schemaVersion field now so consumers do not have to infer later changes.
2. Return sessionId plus sessionCreated/sessionResumed. Get-or-create is convenient, but without that signal a typo can silently start a new conversation. An explicit --create-session-if-missing would be even safer for stateful automation.
3. Define stable non-zero exit codes and a structured error.code; callers should not need to branch on localized messages.
4. Resolve --model through the same provider/model registry used by the profile rather than splitting only on /, and echo the resolved provider/model in the result.
5. Keep the single-object --json contract, but leave room for a future --jsonl event stream when embedders need tool progress and cancellation rather than only the terminal result.

Disclosure: I maintain SandBase Harness, which exposes a similar persistent-session + resumable-event API and a DSH MCP bridge. The most important lesson there was treating the machine-output channel and resume semantics as a public API from day one. Happy to review the eventual flag/output schema.

[denial123789]

This would materially improve embedding. I checked the proposed wiring against rc.8 (141eb6f) and found one identity distinction worth resolving before the flag contract freezes:

• ctx.agents.resume({ resumeSessionId }) is strict resume: it requires existing persisted history and rejects a miss.
• the exact stable sessionId path is rc.8's create-or-resume identity: first use creates; a later mount with persistence present resumes.

So a get-or-create --session-id should map to stable exact sessionId, not directly to resumeSessionId. If strict resume is also useful, it deserves separate explicit semantics; silently creating after a typo forks history.

A few adjacent protocol gates seem important:

1. one exact Session id needs one writer; concurrent headless processes must be serialized, leased, or rejected;
2. resumed cwd and per-run model persistence need explicit rules;
3. model-only shorthand can be ambiguous across providers, so resolved provider/model should be validated and recorded before dispatch;
4. --json stdout should be exactly one versioned document, with all logs/progress on stderr;
5. default JSON must not expose prompts, reasoning, raw tool arguments/results, credentials, or the full event log;
6. tool summaries must cover only the current owned interval (firstSeq before the follow-up), especially on resume;
7. Session flush failure must not produce exit 0; and
8. completed/error/cancelled/startup-failure states need stable JSON + exit-code agreement.

The current rc.8 runner already has a good interval boundary: it records firstSeq, submits once, waits idle, flushes, then folds only that invocation. That can anchor text, terminal reason, and tool counts without replaying old results into the response.

I wrote up a proposed public contract and sixteen-case acceptance matrix here:

• Visual contract: https://sandbaseai.github.io/deepseek-harness-handbook/headless-programmatic-contract.html
• Full guide: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/guides/headless-programmatic-contract.md

[icejean]

I'v integrated DeepSeek Harness into my project DataAI Portal as an option to OpenClaw for China mainland users, you can have a review in my artical "Testing DeepSeek Harness in deep" in Chinese.
The embedded usage is:

  dsh --profile headless \
      --patch ~/.dsh/model-patch-<session_id>.yml \
      --session-id session-<chat_id> \
      "<user message>"

You can chat to analysis data with JupyterLab R/Python kernel backends and switch as your will between the kernels.

You can watch what AI is doing backend by opening a console in JupyterLab, here is the Python console's output, the codes and results.

Also the R kernel.

There's a simple Admin dashboard.

And you can change the LLM model to chat as your will.