@deepseek-ai/dsh-headless 0.1.5-rc.2 → 0.1.6-alpha.2

package/lib/startup.js

@@ -1,10 +1,24 @@
-import { Command } from "commander";
+import { t as boundJsonLine } from "./json-stream-Bh4BGGk9.js";
+import { Command, CommanderError } from "commander";
 import { parseCmdline } from "@deepseek-ai/dsh-cmdline";
+//#region lib/types/startup-internals.js
+/**
+* Process facts the startup provider reads, kept out of the `./startup` entry
+* so substituting them in tests adds no public package API.
+* @module @deepseek-ai/dsh-headless/startup-internals
+*/
+/** Process facts the provider reads; tests substitute them. */
+const internals = {
+	stdinIsTty: () => process.stdin.isTTY,
+	stdout: process.stdout
+};
+//#endregion
 //#region lib/types/startup.js
 /**
-* The one-shot app's command-line provider: it parses the task positional and
-* `--help`, then publishes {@link HEADLESS_STARTUP_SERVICE}. The runner is an
-* ordinary consumer whose lazy config waits for that service.
+* The one-shot app's command-line provider: it parses the task positional,
+* `--session-id`, `--json`, and `--help`, then publishes
+* {@link HEADLESS_STARTUP_SERVICE}. The runner is an ordinary consumer whose
+* lazy config waits for that service.
 * @module @deepseek-ai/dsh-headless/startup
 */
 /** Stable Cordis plugin name. */
@@ -14,27 +28,64 @@ const inject = ["cmdlineArgs"];
 /** Service provided by this plugin and injected by the one-shot runner. */
 const HEADLESS_STARTUP_SERVICE = "headlessStartup";
 /**
-* This app's command: the task positional, its description, and its help text.
+* This app's command: the task positional, its options, and its help text.
 * @returns a fresh program, so one process can parse more than once (tests).
 */
 function headlessCommand() {
-	return new Command().name("dsh --profile headless").description("Answer one task, stream reasoning to stderr, print the final assistant message, and exit.").helpOption("-h, --help", "show this help").argument("[task...]", "the task text; multiple words are joined by spaces").addHelpText("after", `
+	return new Command().name("dsh --profile headless").description("Answer one task and exit; the answer goes to stdout and diagnostics to stderr.").helpOption("-h, --help", "show this help").option("--json", "write newline-delimited run events to stdout instead of the final message").option("--session-id <id>", "adopt the persisted Session with this id; an unknown id is an error").argument("[task...]", "the task text; multiple words are joined by spaces, and `-` reads stdin").addHelpText("after", `
 Examples:
-  dsh --profile headless "run the tests"     answer one task and exit
+  dsh --profile headless "run the tests"          answer one task and exit
+  echo "run the tests" | dsh --profile headless   read the task from stdin
+  dsh --profile headless --json "run the tests"   emit machine-readable run events
+  dsh --profile headless --session-id session-… "continue"   resume an existing Session
 `);
 }
 /**
+* Whether the raw invocation asks for the machine-readable stream. The scan
+* stops at `--` and skips a `--session-id` value, so a literal `--json` used as
+* an option value or a positional never installs the JSON error override.
+* @param argv - the invocation's raw arguments.
+* @returns whether `--json` is a real flag of this invocation.
+*/
+function jsonRequested(argv) {
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		if (argument === "--") return false;
+		if (argument === "--json") return true;
+		if (argument === "--session-id") index += 1;
+	}
+	return false;
+}
+/**
 * Parse and provide the one-shot task as an ordinary Cordis service. The
-* command's action publishes the task; a missing or whitespace-only task is a
-* usage error, so on rejection (and on `--help`) nothing is provided.
+* command's action publishes the task; a missing task on an interactive stdin
+* is a usage error, so on rejection (and on `--help`) nothing is provided.
 * @param ctx - plugin context carrying the command line.
 */
 function apply(ctx) {
 	const program = headlessCommand();
+	if (jsonRequested(ctx.get("cmdlineArgs")?.get() ?? [])) program.error = (message, errorOptions) => {
+		const payload = boundJsonLine({
+			type: "error",
+			message: message.replace(/^error: /, "")
+		});
+		internals.stdout.write(`${payload}\n`);
+		throw new CommanderError(1, errorOptions?.code ?? "commander.error", message);
+	};
 	program.action(() => {
-		const task = program.args.join(" ");
-		if (task.trim() === "") program.error("error: a task is required, for example: dsh --profile headless \"run the tests\"");
-		ctx.provide(HEADLESS_STARTUP_SERVICE, { task });
+		if (program.args.length > 1 && program.args.includes("-")) program.error("error: `-` must be the only task argument");
+		const joined = program.args.join(" ");
+		if (program.args.length > 0 && joined.trim() === "") program.error("error: a task is required, for example: dsh --profile headless \"run the tests\"");
+		const task = program.args.length === 0 ? void 0 : joined;
+		if (task === void 0 && internals.stdinIsTty()) program.error("error: a task is required, for example: dsh --profile headless \"run the tests\"");
+		const options = program.opts();
+		const sessionId = options.sessionId;
+		if (sessionId !== void 0 && sessionId.trim() === "") program.error("error: --session-id requires a non-empty session id");
+		ctx.provide(HEADLESS_STARTUP_SERVICE, {
+			task,
+			sessionId,
+			json: options.json === true
+		});
 	});
 	parseCmdline(ctx, program);
 }

package/lib/types/index.d.ts

@@ -1,9 +1,11 @@
 /**
  * @deepseek-ai/dsh-headless — one-shot direct Agent driver. The bundle patch
  * rides over dsh-base without Host, HTTP, or browser plugins; this runner
- * creates one Agent through the core registry, drives the task to quiescence,
- * streams provider reasoning to stderr, flushes its Session, prints the final
- * assistant text to stdout, and exits.
+ * creates one Agent through the core registry (or adopts the exact Session a
+ * `--session-id` names), drives the task to quiescence, streams provider
+ * reasoning to stderr, flushes its Session, prints the final assistant text to
+ * stdout, and exits. With `--json` it projects the run as newline-delimited
+ * events instead of the final text.
  *
  * @module @deepseek-ai/dsh-headless
  */
@@ -13,33 +15,20 @@ import z from '@deepseek-ai/schemastery';
 export declare const name = "headless-runner";
 /** Core services required before the one-shot turn can start. */
 export declare const inject: string[];
-/** Plugin config: the task resolved from this app's injected provider service. */
+/** Plugin config: the task and run options resolved from this app's injected provider service. */
 export interface Config {
-    /** The prompt text for the single run. */
-    task: string;
+    /** The prompt text for the single run; absent when the task arrives on stdin. */
+    task?: string;
+    /** Exact Session identity to adopt; absent for a fresh random identity. An id with no stored Session fails. */
+    sessionId?: string;
+    /** Whether stdout carries the machine-readable event stream instead of final text. */
+    json?: boolean;
 }
 export declare const Config: z<Config>;
-/** Process-facing effects of one run: output streams plus the launcher's bounded exit request. */
-interface HeadlessIo {
-    stdout: {
-        write(chunk: string): unknown;
-    };
-    stderr: {
-        write(chunk: string): unknown;
-    };
-    /** Request process exit with `code` after the tree disposes. */
-    exit(code: number): void;
-}
-/** The process streams the runner writes to; tests substitute captures. */
-export declare const internals: {
-    stdout: HeadlessIo['stdout'];
-    stderr: HeadlessIo['stderr'];
-};
 /**
  * Mount the one-shot direct driver.
  * @param ctx - plugin context carrying core services and the launcher-provided exit request.
- * @param config - validated task config.
+ * @param config - validated task and run options.
  */
 export declare function apply(ctx: Context, config: Config): void;
-export {};
 //# sourceMappingURL=index.d.ts.map

package/lib/types/json-stream.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `--json` run projection: a bounded, ordered event stream derived from one
+ * Agent's durable Session events. Every projected event is a commit point:
+ * text and reasoning come from committed `assistant/message` content, never
+ * from a live attempt that may still be retried or discarded, so the stream
+ * never carries content the durable log does not contain.
+ * @module @deepseek-ai/dsh-headless/json-stream
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+/** Default per-string and per-key cap applied to every bounded projected payload. */
+export declare const MAX_STRING_BYTES: number;
+/** Default cap on one projected event's serialized bytes, newline included; the terminal `final` is exempt. */
+export declare const MAX_EVENT_BYTES: number;
+/** The stdout sink a projection writes newline-delimited events to. */
+export interface JsonSink {
+    /** Write one chunk of the event stream. */
+    write(chunk: string): unknown;
+}
+/** Tunables for {@link projectJsonRun}; every field defaults. */
+export interface JsonProjectionOptions {
+    /** Working directory reported by the opening `session` event. */
+    cwd?: string;
+    /** Per-string and per-key byte cap; longer values are truncated and flagged. */
+    maxStringBytes?: number;
+}
+/** The live handle of one `--json` projection. */
+export interface JsonProjection {
+    /** Write the terminal `final` event carrying the run's answer text. */
+    finish(text: string): void;
+    /** Stop observing the Session. */
+    dispose(): void;
+}
+/**
+ * Serialize one projected payload under both limits: every string and key is
+ * capped at `maxStringBytes`, and the serialized line at `maxEventBytes`. The
+ * line cap reserves the newline the writer appends, so the complete record
+ * stays within it. When the line is still too long, scalar fields survive and
+ * structured fields are dropped; when even those are too long, only `type` and
+ * `truncated` remain.
+ * @param event - the event payload to serialize.
+ * @param maxStringBytes - per-string and per-key byte cap.
+ * @param maxEventBytes - cap on the serialized line plus its trailing newline.
+ * @returns the bounded JSON line, without a trailing newline.
+ */
+export declare function boundJsonLine(event: Record<string, unknown>, maxStringBytes?: number, maxEventBytes?: number): string;
+/**
+ * Project one Agent's run as newline-delimited JSON on `sink`.
+ *
+ * The opening `session` event is written before the subscription starts, so a
+ * caller must invoke this before submitting the task. Text and reasoning are
+ * emitted only when the step's `assistant/message` commits them, and the
+ * terminal `final` event carries the same lossless answer the default mode
+ * prints (it is deliberately not bounded).
+ * @param ctx - plugin context carrying the live Session feed.
+ * @param agent - the exact Agent whose events belong to this invocation.
+ * @param sink - stdout sink receiving one JSON object per line.
+ * @param options - projection tunables.
+ * @returns the projection handle that finishes or disposes the stream.
+ */
+export declare function projectJsonRun(ctx: Context, agent: Agent, sink: JsonSink, options?: JsonProjectionOptions): JsonProjection;
+//# sourceMappingURL=json-stream.d.ts.map

package/lib/types/runner-internals.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Process streams the runner reads and writes, kept out of the package entry so
+ * substituting them in tests adds no public package API. The shape matches the
+ * runner's own IO carrier structurally.
+ * @module @deepseek-ai/dsh-headless/runner-internals
+ */
+/** The process streams the runner reads and writes; tests substitute captures. */
+export declare const internals: {
+    stdout: {
+        write(chunk: string): unknown;
+    };
+    stderr: {
+        write(chunk: string): unknown;
+    };
+    readStdin: () => Promise<string>;
+};
+//# sourceMappingURL=runner-internals.d.ts.map

package/lib/types/startup-internals.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Process facts the startup provider reads, kept out of the `./startup` entry
+ * so substituting them in tests adds no public package API.
+ * @module @deepseek-ai/dsh-headless/startup-internals
+ */
+/** Process facts the provider reads; tests substitute them. */
+export declare const internals: {
+    stdinIsTty: () => boolean;
+    stdout: {
+        write(chunk: string): unknown;
+    };
+};
+//# sourceMappingURL=startup-internals.d.ts.map

package/lib/types/startup.d.ts

@@ -1,7 +1,8 @@
 /**
- * The one-shot app's command-line provider: it parses the task positional and
- * `--help`, then publishes {@link HEADLESS_STARTUP_SERVICE}. The runner is an
- * ordinary consumer whose lazy config waits for that service.
+ * The one-shot app's command-line provider: it parses the task positional,
+ * `--session-id`, `--json`, and `--help`, then publishes
+ * {@link HEADLESS_STARTUP_SERVICE}. The runner is an ordinary consumer whose
+ * lazy config waits for that service.
  * @module @deepseek-ai/dsh-headless/startup
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -13,13 +14,17 @@ export declare const inject: string[];
 export declare const HEADLESS_STARTUP_SERVICE = "headlessStartup";
 /** What the runner row reads from {@link HEADLESS_STARTUP_SERVICE}. */
 export interface HeadlessStartupValues {
-    /** The task text this invocation asked for. */
-    task: string;
+    /** The task text this invocation asked for; absent when the runner reads stdin. */
+    task: string | undefined;
+    /** Exact Session identity to adopt; absent for a fresh random identity. */
+    sessionId: string | undefined;
+    /** Whether stdout carries the machine-readable event stream instead of final text. */
+    json: boolean;
 }
 /**
  * Parse and provide the one-shot task as an ordinary Cordis service. The
- * command's action publishes the task; a missing or whitespace-only task is a
- * usage error, so on rejection (and on `--help`) nothing is provided.
+ * command's action publishes the task; a missing task on an interactive stdin
+ * is a usage error, so on rejection (and on `--help`) nothing is provided.
  * @param ctx - plugin context carrying the command line.
  */
 export declare function apply(ctx: Context): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-headless",
   "description": "The dsh one-shot bundle: a direct core Agent/Session runner over dsh-base with no Host, HTTP, or browser layer",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -30,6 +30,7 @@
     "lib/index.js",
     "lib/startup.js",
     "cordis.patch.yml",
+    "lib/json-stream-*.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
@@ -40,28 +41,31 @@
   },
   "dependencies": {
     "commander": "^15.0.0",
-    "@deepseek-ai/dsh-brand": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-cmdline": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-code-runtime-worker-thread": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-cmdline": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.6-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent-default-model": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent-default-model": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.2"
   }
 }