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

package/lib/index.js

@@ -1,3 +1,4 @@
+import { n as projectJsonRun, t as boundJsonLine } from "./json-stream-Bh4BGGk9.js";
 import { randomUUID } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import { brandString } from "@deepseek-ai/dsh-brand";
@@ -5,16 +6,95 @@ import { installModelSelection } from "@deepseek-ai/dsh-agent";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { assertNever } from "@deepseek-ai/dsh-util-values";
 import { SessionSeq } from "@deepseek-ai/dsh-session";
+import { SessionQueryError } from "@deepseek-ai/dsh-session-query";
+//#region lib/types/runner-internals.js
+/**
+* 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. */
+const internals = {
+	stdout: process.stdout,
+	stderr: process.stderr,
+	readStdin: async () => {
+		const chunks = [];
+		for await (const chunk of process.stdin) chunks.push(chunk);
+		return Buffer.concat(chunks).toString("utf8");
+	}
+};
+//#endregion
 //#region lib/types/index.js
 /**
 * @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
 */
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 /** Stable Cordis plugin name. */
 const name = "headless-runner";
 /** Core services required before the one-shot turn can start. */
@@ -23,12 +103,11 @@ const inject = [
 	"agents",
 	"sessions"
 ];
-const Config = z.object({ task: z.string().required() });
-/** The process streams the runner writes to; tests substitute captures. */
-const internals = {
-	stdout: process.stdout,
-	stderr: process.stderr
-};
+const Config = z.object({
+	task: z.string(),
+	sessionId: z.string(),
+	json: z.boolean()
+});
 /** Aggregate the last assistant text and turn outcome in one owned interval. */
 function summarize(session, firstSeq) {
 	let started = false;
@@ -113,63 +192,165 @@ function streamReasoning(ctx, agent, stderr) {
 		close();
 	};
 }
+/** Iterate a live Session's durable events in order. */
+function* liveEvents(session) {
+	const length = session.seq;
+	for (let seq = 0; seq < length; seq++) {
+		const event = session.eventAt(SessionSeq(seq));
+		if (event === void 0) throw new Error(`headless adoption cannot read seq ${String(seq)} below captured length ${String(length)}`);
+		yield event;
+	}
+}
+/**
+* The preset a Session currently runs under: its creation header advanced by
+* the last `agent-preset/selected` event. The header is only a creation fact;
+* the presets plugin reconstructs a session's composition from the projection.
+*/
+function currentPreset(header, events, sessionId) {
+	let preset = header.agentPreset;
+	for (const event of events) {
+		const candidate = event;
+		if (candidate.type !== "agent-preset/selected") continue;
+		const selected = candidate.data?.agentPreset;
+		if (typeof selected !== "string" || selected === "") throw new Error(`session "${sessionId}" records a malformed agent-preset/selected event and cannot be adopted`);
+		preset = selected;
+	}
+	return preset;
+}
+/** Reject a Session the one-shot runner must not adopt. */
+function assertAdoptable(header, events, sessionId, cwd) {
+	const preset = currentPreset(header, events, sessionId);
+	if (preset !== void 0) throw new Error(`session "${sessionId}" runs under agent preset "${preset}", which the one-shot runner does not compose`);
+	if (header.origin === "subagent" || header.parentSession !== void 0) throw new Error(`session "${sessionId}" is a subagent or forked session and cannot be driven directly`);
+	if (header.cwd === void 0) throw new Error(`session "${sessionId}" recorded no working directory, so it cannot be adopted`);
+	if (header.cwd !== cwd) throw new Error(`session "${sessionId}" was recorded in "${header.cwd}", not "${cwd}"`);
+}
+/**
+* Resolve the Agent for one run: adopt the persisted Session with the requested
+* id. The identity must already exist, and no Agent may be live under it; a
+* first round omits the option instead, so a typo cannot pass as a brand-new
+* conversation.
+* @param ctx - plugin context carrying the Session query service.
+* @param agents - the core Agent registry.
+* @param sessionId - exact Session identity to adopt.
+* @param agentOptions - provider/model pair for this run.
+* @param setup - per-Agent scope setup installing the model selection.
+* @param cwd - working directory resolved in the mounted filesystem.
+* @returns the resumed Agent.
+*/
+async function resolveAgent(ctx, agents, sessionId, agentOptions, setup, cwd) {
+	if (ctx.get("sessionPersistence") === void 0) throw new Error("headless --session-id requires the sessionPersistence service; the Session would not survive this process");
+	const query = ctx.get("sessionQuery");
+	if (query === void 0) throw new Error("headless --session-id requires the sessionQuery service; dsh-base provides it");
+	const live = agents.get(sessionId);
+	if (live !== void 0) {
+		assertAdoptable(live.session.header, liveEvents(live.session), sessionId, cwd);
+		throw new Error(`session "${sessionId}" is live in this process, so the one-shot runner cannot own an exclusive run interval`);
+	}
+	try {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			const observation = __addDisposableResource(env_1, await query.observeSession(sessionId), false);
+			assertAdoptable(observation.header, observation.events, sessionId, cwd);
+			const { agent } = await agents.resume({
+				resumeSessionId: sessionId,
+				agentOptions,
+				setup
+			});
+			assertAdoptable(agent.session.header, liveEvents(agent.session), sessionId, cwd);
+			return agent;
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources(env_1);
+		}
+	} catch (error) {
+		if (!(error instanceof SessionQueryError) || error.code !== "SESSION_QUERY_SESSION_NOT_FOUND") throw error;
+		throw new Error(`session "${sessionId}" does not exist; omit --session-id to start a new Session`);
+	}
+}
 /** Report an unexpected direct-driver failure and request a failing exit. */
-function fail(io, error) {
-	io.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`);
+function fail(io, error, json) {
+	const message = error instanceof Error ? error.message : String(error);
+	if (json) io.stdout.write(`${boundJsonLine({
+		type: "error",
+		message
+	})}\n`);
+	io.stderr.write(`dsh: ${message}\n`);
 	io.exit(1);
 }
 /**
-* Run one task through a freshly created Agent and request process exit.
+* Run one task through one Agent and request process exit.
 * @param ctx - plugin context carrying the Agent, default model, Session, and launcher IO services.
-* @param task - one-shot task text.
+* @param config - task, optional exact Session identity, and output mode.
 * @param io - process-facing effects.
 */
-async function run(ctx, task, io) {
+async function run(ctx, config, io) {
 	await ctx.get("loader")?.await();
 	const agents = ctx.get("agents");
 	const defaultModel = ctx.get("agentDefaultModel");
 	const sessions = ctx.get("sessions");
 	if (agents === void 0 || defaultModel === void 0 || sessions === void 0) return;
+	if (config.sessionId !== void 0 && config.sessionId.trim() === "") throw new Error("headless-runner: sessionId must not be blank");
+	const task = config.task === void 0 || config.task === "-" ? await internals.readStdin() : config.task;
+	if (task.trim() === "") throw new Error("a task is required, for example: dsh --profile headless \"run the tests\"");
 	const selection = defaultModel.currentSelection();
-	const { agent } = await agents.create({
-		sessionId: brandString(`session-${randomUUID()}`),
-		meta: { cwd: process.cwd() },
-		agentOptions: {
-			provider: selection.provider,
-			model: selection.model
-		},
-		setup: (agentCtx) => {
-			installModelSelection(agentCtx, {
-				current: selection,
-				assembled: void 0
-			});
-		}
-	});
+	const agentOptions = {
+		provider: selection.provider,
+		model: selection.model
+	};
+	const setup = (agentCtx) => {
+		installModelSelection(agentCtx, {
+			current: selection,
+			assembled: void 0
+		});
+	};
+	const sessionId = brandString(config.sessionId ?? `session-${randomUUID()}`);
+	const fs = ctx.get("fs");
+	const cwd = fs === void 0 ? process.cwd() : fs.processPath(await fs.resolve("."));
+	const agent = config.sessionId === void 0 ? (await agents.create({
+		sessionId,
+		meta: { cwd },
+		agentOptions,
+		setup
+	})).agent : await resolveAgent(ctx, agents, sessionId, agentOptions, setup, cwd);
 	await agent.whenIdle();
+	if (config.sessionId !== void 0) assertAdoptable(agent.session.header, liveEvents(agent.session), sessionId, cwd);
 	const firstSeq = agent.session.seq;
-	const stopReasoning = streamReasoning(ctx, agent, io.stderr);
+	const projection = config.json === true ? projectJsonRun(ctx, agent, io.stdout, { cwd }) : void 0;
+	const stopReasoning = projection === void 0 ? streamReasoning(ctx, agent, io.stderr) : void 0;
 	try {
-		agent.followup(createUserMessage({
-			content: [{
-				type: "text",
-				text: task
-			}],
-			source: { kind: "user" }
-		}));
-		await agent.whenIdle();
+		try {
+			agent.followup(createUserMessage({
+				content: [{
+					type: "text",
+					text: task
+				}],
+				source: { kind: "user" }
+			}));
+			await agent.whenIdle();
+		} finally {
+			stopReasoning?.();
+		}
+		await sessions.flush(agent.session);
+		const outcome = summarize(agent.session, firstSeq);
+		if (projection === void 0) io.stdout.write(outcome.text + "\n");
+		else projection.finish(outcome.text);
+		if (outcome.reason?.kind === "error") io.stderr.write(`dsh: ${outcome.reason.error.code}: ${outcome.reason.error.message}\n`);
+		io.exit(outcome.reason?.kind === "completed" ? 0 : 1);
 	} finally {
-		stopReasoning();
+		projection?.dispose();
 	}
-	await sessions.flush(agent.session);
-	const outcome = summarize(agent.session, firstSeq);
-	io.stdout.write(outcome.text + "\n");
-	if (outcome.reason?.kind === "error") io.stderr.write(`dsh: ${outcome.reason.error.code}: ${outcome.reason.error.message}\n`);
-	io.exit(outcome.reason?.kind === "completed" ? 0 : 1);
 }
 /**
 * 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.
 */
 function apply(ctx, config) {
 	const exit = ctx.get("appExit");
@@ -179,9 +360,9 @@ function apply(ctx, config) {
 		stderr: internals.stderr,
 		exit
 	};
-	run(ctx, config.task, io).catch((error) => {
-		fail(io, error);
+	run(ctx, config, io).catch((error) => {
+		fail(io, error, config.json === true);
 	});
 }
 //#endregion
-export { Config, apply, inject, internals, name };
+export { Config, apply, inject, name };

package/lib/json-stream-Bh4BGGk9.js

@@ -0,0 +1,280 @@
+import { lastAssistantStreamChunk } from "@deepseek-ai/dsh-llm/assistant-stream";
+//#region lib/types/json-stream.js
+/**
+* `--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
+*/
+/** Default per-string and per-key cap applied to every bounded projected payload. */
+const MAX_STRING_BYTES = 8 * 1024;
+/** Default cap on one projected event's serialized bytes, newline included; the terminal `final` is exempt. */
+const MAX_EVENT_BYTES = 32 * 1024;
+/** Bytes every newline-delimited writer appends after one serialized event. */
+const LINE_TERMINATOR_BYTES = 1;
+/** Truncate one UTF-8 string to `maxBytes`, dropping a split trailing character. */
+function truncateUtf8(text, maxBytes) {
+	const decoded = Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+	return decoded.endsWith("�") ? decoded.slice(0, -1) : decoded;
+}
+/** Cap one object key, flagging the payload when it was cut. */
+function boundKey(key, maxBytes, state) {
+	if (Buffer.byteLength(key, "utf8") <= maxBytes) return key;
+	state.truncated = true;
+	return truncateUtf8(key, maxBytes);
+}
+/** Maximum container depth one projected payload keeps before the tail is cut. */
+const MAX_DEPTH = 64;
+/** Recursively cap every string in one JSON-serializable value, keys included. */
+function boundValue(value, maxBytes, state, depth = 0) {
+	if (typeof value === "string") {
+		if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+		state.truncated = true;
+		return truncateUtf8(value, maxBytes);
+	}
+	if (Array.isArray(value)) {
+		if (depth >= MAX_DEPTH) {
+			state.truncated = true;
+			return "[truncated: depth]";
+		}
+		return value.map((item) => boundValue(item, maxBytes, state, depth + 1));
+	}
+	if (value !== null && typeof value === "object") {
+		if (depth >= MAX_DEPTH) {
+			state.truncated = true;
+			return "[truncated: depth]";
+		}
+		const bounded = Object.create(null);
+		for (const [key, item] of Object.entries(value)) bounded[boundKey(key, maxBytes, state)] = boundValue(item, maxBytes, state, depth + 1);
+		return bounded;
+	}
+	return value;
+}
+/**
+* Bound every string and key in one projected payload, adding `truncated: true`
+* when any was cut. {@link boundJsonLine} composes this with the whole-line cap.
+* @param event - the event payload to bound.
+* @param maxStringBytes - per-string and per-key byte cap.
+* @returns a copy with every over-long string and key truncated.
+*/
+function boundJsonEvent(event, maxStringBytes = MAX_STRING_BYTES) {
+	const state = { truncated: false };
+	const bounded = boundValue(event, maxStringBytes, state);
+	if (state.truncated) bounded.truncated = true;
+	return bounded;
+}
+/**
+* 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.
+*/
+function boundJsonLine(event, maxStringBytes = MAX_STRING_BYTES, maxEventBytes = MAX_EVENT_BYTES) {
+	const limit = maxEventBytes - LINE_TERMINATOR_BYTES;
+	const bounded = boundJsonEvent(event, maxStringBytes);
+	const line = JSON.stringify(bounded);
+	if (Buffer.byteLength(line, "utf8") <= limit) return line;
+	const scalars = Object.create(null);
+	for (const [key, value] of Object.entries(bounded)) if (value === null || typeof value !== "object") scalars[key] = value;
+	scalars.truncated = true;
+	const short = JSON.stringify(scalars);
+	if (Buffer.byteLength(short, "utf8") <= limit) return short;
+	return JSON.stringify({
+		type: bounded.type,
+		truncated: true
+	});
+}
+/**
+* Parse raw tool-call arguments as the executor does: empty input is `{}`,
+* invalid or non-round-trippable JSON (a non-finite number) stays text.
+*/
+function parseArguments(raw) {
+	if (raw === "") return {};
+	const seen = { nonFinite: false };
+	try {
+		const parsed = JSON.parse(raw, (_key, value) => {
+			if (typeof value === "number" && !Number.isFinite(value)) seen.nonFinite = true;
+			return value;
+		});
+		return seen.nonFinite ? raw : parsed;
+	} catch {
+		return raw;
+	}
+}
+/** Join the text blocks of a tool result's model-facing content. */
+function resultText(blocks) {
+	return blocks.filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("");
+}
+/** The usage a provider reported in one attempt's stream, if any. */
+function streamUsage(stream) {
+	return lastAssistantStreamChunk(stream, "usage")?.usage;
+}
+/**
+* Accumulate one step's usage across its attempts. A retried attempt keeps its
+* usage only in its `assistant/attempt` stream, so the committed message alone
+* would under-report billed tokens. An attempt that reports no sample makes the
+* step total unknowable, so the step omits usage entirely rather than publish a
+* partial sum as if it were complete; an optional bucket is summed only when
+* every contribution reports it.
+* @param state - usage accumulated so far and whether it is still complete.
+* @param next - usage reported by the next attempt.
+* @returns the updated state.
+*/
+function addUsage(state, next) {
+	if (next === void 0) return {
+		usage: state.usage,
+		complete: false
+	};
+	if (state.usage === void 0) return {
+		usage: next,
+		complete: state.complete
+	};
+	const total = state.usage;
+	const sum = (a, b) => a === void 0 || b === void 0 ? void 0 : a + b;
+	const totalTokens = sum(total.totalTokens, next.totalTokens);
+	const cacheReadTokens = sum(total.cacheReadTokens, next.cacheReadTokens);
+	const cacheWriteTokens = sum(total.cacheWriteTokens, next.cacheWriteTokens);
+	const reasoningTokens = sum(total.reasoningTokens, next.reasoningTokens);
+	return {
+		usage: {
+			inputTokens: total.inputTokens + next.inputTokens,
+			outputTokens: total.outputTokens + next.outputTokens,
+			...totalTokens === void 0 ? {} : { totalTokens },
+			...cacheReadTokens === void 0 ? {} : { cacheReadTokens },
+			...cacheWriteTokens === void 0 ? {} : { cacheWriteTokens },
+			...reasoningTokens === void 0 ? {} : { reasoningTokens }
+		},
+		complete: state.complete
+	};
+}
+/**
+* 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.
+*/
+function projectJsonRun(ctx, agent, sink, options = {}) {
+	const maxStringBytes = options.maxStringBytes ?? 8192;
+	let disposed = false;
+	let stepUsage = {
+		usage: void 0,
+		complete: true
+	};
+	const write = (event) => {
+		sink.write(`${boundJsonLine(event, maxStringBytes)}\n`);
+	};
+	const onSessionEvent = (session, event) => {
+		if (session !== agent.session) return;
+		switch (event.type) {
+			case "turn/start":
+				write({
+					type: "status",
+					phase: "turn_start",
+					turn: event.data.turn
+				});
+				return;
+			case "step/start":
+				write({
+					type: "status",
+					phase: "step_start",
+					turn: event.data.turn,
+					step: event.data.step
+				});
+				return;
+			case "assistant/attempt":
+				stepUsage = addUsage(stepUsage, streamUsage(event.data.stream));
+				return;
+			case "assistant/message":
+				stepUsage = addUsage(stepUsage, event.data.usage ?? streamUsage(event.data.stream));
+				for (const block of event.data.message.content) if (block.type === "reasoning") write({
+					type: "thinking",
+					text: block.text
+				});
+				else if (block.type === "text") write({
+					type: "text",
+					text: block.text
+				});
+				return;
+			case "step/end": {
+				const { usage, complete } = stepUsage;
+				stepUsage = {
+					usage: void 0,
+					complete: true
+				};
+				write({
+					type: "status",
+					phase: "step_end",
+					turn: event.data.turn,
+					step: event.data.step,
+					...complete && usage !== void 0 ? { usage } : {}
+				});
+				return;
+			}
+			case "turn/end":
+				write({
+					type: "status",
+					phase: "turn_end",
+					turn: event.data.turn,
+					reason: event.data.reason
+				});
+				return;
+			case "tool/call":
+				write({
+					type: "tool_call",
+					callId: event.data.callId,
+					tool: event.data.name,
+					input: parseArguments(event.data.arguments)
+				});
+				return;
+			case "tool/result": {
+				if (event.surfaceOp !== "append") return;
+				const block = event.data.message.content[0];
+				write({
+					type: "tool_result",
+					callId: block.toolCallId,
+					status: block.isError === true ? "error" : "completed",
+					result: resultText(block.content)
+				});
+				return;
+			}
+			default: return;
+		}
+	};
+	write({
+		type: "session",
+		sessionId: agent.id,
+		cwd: options.cwd ?? process.cwd()
+	});
+	const stopSession = ctx.on("session/event", onSessionEvent);
+	return {
+		finish(text) {
+			if (disposed) return;
+			sink.write(`${JSON.stringify({
+				type: "final",
+				text
+			})}\n`);
+		},
+		dispose() {
+			disposed = true;
+			stopSession();
+		}
+	};
+}
+//#endregion
+export { projectJsonRun as n, boundJsonLine as t };