@stackstackstack/dsh-agent-loop 0.1.5

package/lib/invariant.js

@@ -0,0 +1,42 @@
+import { isAgentLoopRequest } from "@stackstackstack/dsh-llm";
+import { foldRequestHeader } from "@stackstackstack/dsh-session";
+//#region lib/types/invariant.js
+/**
+* Package-owned request-reconstruction invariant for loop-built LLM calls.
+* @module @stackstackstack/dsh-agent-loop/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-agent-loop";
+/** Cordis companion plugin name. */
+const name = "agent-loop-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Install the request-reconstruction contribution into its child registration fiber. */
+const install = Object.assign((ctx, fail) => {
+	ctx.on("llm/stream", (options, next) => {
+		if (!isAgentLoopRequest(options)) return next();
+		if (!Object.isFrozen(options)) fail("a loop-built request must be frozen");
+		if (options.sessionId === void 0) fail("a loop-built request must carry a session id");
+		const session = ctx.sessions.get(options.sessionId);
+		if (!session) fail(`a loop-built request must carry a live session id, got "${String(options.sessionId)}"`);
+		if (!Object.isFrozen(options.messages)) fail("a loop-built request must carry a frozen messages array");
+		const events = session.events;
+		if (!events.some((event) => event.type === "step/start")) return fail("a loop-built request with no step/start in its session log");
+		const header = foldRequestHeader(events);
+		if (header === void 0) return fail("a loop-built request with no request/header event in its session log");
+		const expected = session.deriveMessages();
+		if (JSON.stringify(options.messages) !== JSON.stringify(expected)) fail(`llm request for session "${String(session.id)}" diverges from the dispatch-time durable derivation (log-reconstruction desync)`);
+		if (!(options.model === header.config.model && options.system === header.system && options.temperature === header.config.temperature && options.maxTokens === header.config.maxTokens && JSON.stringify(options.stop) === JSON.stringify(header.config.stop) && JSON.stringify(options.tools ?? []) === JSON.stringify(header.tools ?? []))) fail(`llm request for session "${String(session.id)}" diverges from the folded request header`);
+		return next();
+	}, {
+		global: true,
+		prepend: true
+	});
+}, { inject: ["sessions"] });
+/**
+* Register the agent-loop invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/agent.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Default Agent driver over queued turns and step-boundary input. Every request
+ * is derived from the session log.
+ * @module dsh-agent-loop/agent
+ */
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget } from '@stackstackstack/dsh-agent';
+import { Inbox } from '@stackstackstack/dsh-agent';
+import type { Scope } from '@stackstackstack/dsh-scope';
+import type { Session, SessionId, UserMessage } from '@stackstackstack/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+/** Drives one session through turn and step boundaries. */
+export declare class ReactLoopAgent implements Agent {
+    private loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    readonly inbox: Inbox;
+    private phase;
+    private activityDone;
+    /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */
+    readonly scope: Scope;
+    readonly ctx: Context;
+    /** Fused dispatcher, built once in the constructor so hot-path dispatches never allocate. */
+    private readonly dispatch;
+    /** Whether this loop instance has appended its initial/resume request anchor. */
+    private requestHeaderLogged;
+    private readonly runtimeContext;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session);
+    get status(): AgentStatus;
+    /** Commit a phase and publish its externally visible status transition. */
+    private setPhase;
+    send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;
+    followup(input: UserMessage): void;
+    steer(input: UserMessage): void;
+    inject(input: UserMessage): void;
+    cancel(cause: AgentCancelCause, options?: CancelOptions): void;
+    runMaintenance<T>(job: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * Start one driver, or latch its wake behind maintenance or an aborted
+     * activity. A wake sent while idle always opens its turn boundary, even
+     * when its message was cleared; only a latched replay is suppressed when
+     * the queue no longer holds the wake.
+     * @param wakeAfterAbort - the {@link send} classification, captured before
+     *   the inbox insertion so a reentrant cancel cannot reclassify it.
+     */
+    private wakeDriver;
+    whenIdle(): Promise<void>;
+    /** Report one failure at its live boundary, then preserve it for driver containment. */
+    private throwError;
+    private kick;
+    private preStep;
+    /** Open one turn before claiming its first proposed step. */
+    private turn;
+    private step;
+    /**
+     * Compose one frozen request and bind it to the adapter registration that
+     * resolved its exact-model defaults.
+     */
+    private buildRequest;
+}
+//# sourceMappingURL=agent.d.ts.map

package/lib/types/constants.d.ts

@@ -0,0 +1,6 @@
+/** Shared agent-loop scheduler defaults.
+ * @module dsh-agent-loop/constants
+ */
+/** Default maximum in-flight parallel-safe calls per agent step. */
+export declare const DEFAULT_MAX_PARALLEL_TOOL_CALLS = 10;
+//# sourceMappingURL=constants.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Concrete agent-loop plugin: creates scoped ReactLoopAgents, publishes them
+ * through the agent/session registries, and owns their ordered teardown.
+ *
+ * @module @stackstackstack/dsh-agent-loop
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { Agent, AgentFactory, AgentHandle, AgentOptions, CreateAgentOptions, ResumeAgentOptions } from '@stackstackstack/dsh-agent';
+import { SessionId } from '@stackstackstack/dsh-session';
+import type { SessionHeader } from '@stackstackstack/dsh-session';
+import { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from './constants.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoop: AgentLoop;
+        /**
+         * Launcher-owned exact session identities for configured agents, keyed by
+         * the agent's config `id` and set with `ctx.provide()` before any Loader
+         * entry mounts (see {@link CONFIGURED_AGENT_IDENTITIES_KEY}). A launcher
+         * owns identity because only it knows whether the session already exists,
+         * while the `cordis.yml` row keeps the model route as ordinary patchable
+         * config. An entry with no matching key keeps its configured identity.
+         */
+        configuredAgentIdentities?: ConfiguredAgentIdentities;
+    }
+    interface Events {
+        /**
+         * A declarative agent entry failed before it could publish a live agent.
+         * Consumers that buffer work for the configured identity use this
+         * transient signal to reject that work instead of waiting forever. Normal
+         * factory teardown suppresses failures from the cancelled startup attempt.
+         * @param payload.sessionId - exact shared agent/session identity that failed startup.
+         * @param payload.error - persistence, setup, or publication failure.
+         * @mode emit
+         */
+        'agent-loop/config-start-failed'(payload: {
+            sessionId: SessionId;
+            error: unknown;
+        }): void;
+    }
+}
+export { DEFAULT_MAX_PARALLEL_TOOL_CALLS };
+/**
+ * One launcher-selected session identity for a configured agent. `resume`
+ * distinguishes rehydrating existing persisted history from creating the
+ * session fresh under that exact id, which the two config keys express as
+ * `resumeSessionId` and `sessionId`.
+ */
+export interface LauncherAgentIdentity {
+    /** Exact session id to create fresh or resume. */
+    id: SessionId;
+    /** Resume existing persisted history instead of creating the session fresh. */
+    resume: boolean;
+}
+/** Launcher-selected identities keyed by the configured agent's `id`. */
+export interface ConfiguredAgentIdentities extends Readonly<Record<string, LauncherAgentIdentity>> {
+}
+/**
+ * Context key a launcher sets before any Loader entry mounts
+ * (`ctx.provide(CONFIGURED_AGENT_IDENTITIES_KEY, identities)`) to fix
+ * configured agents' session identities without a config key, so an overlay
+ * repointing the row's model route cannot drop them.
+ */
+export declare const CONFIGURED_AGENT_IDENTITIES_KEY = "configuredAgentIdentities";
+/** Settings namespace carrying the tool-call parallelism a user owns. */
+export declare const AGENT_LOOP_SETTINGS_NAMESPACE: import("@stackstackstack/dsh-settings").SettingsNamespace;
+/**
+ * The agent-loop fields a user owns. Deliberately a strict subset of
+ * {@link Config}: `agents` is a boot-time composition array consumed once when
+ * the service starts, so a stored change could only look like it had an effect.
+ */
+export interface AgentLoopSettings {
+    /** Maximum parallel-safe calls in flight per agent step. */
+    maxParallelToolCalls: number;
+}
+/** Schema of the agent-loop settings section. */
+export declare const AGENT_LOOP_SETTINGS_SCHEMA: z<AgentLoopSettings>;
+/** Agent-loop plugin configuration. */
+export interface Config {
+    /**
+     * Maximum parallel-safe calls in flight per agent step. `1` is serial;
+     * omission defaults to {@link DEFAULT_MAX_PARALLEL_TOOL_CALLS}.
+     */
+    maxParallelToolCalls?: number;
+    /** Agents created or resumed at plugin startup. */
+    agents: (AgentOptions & {
+        /** Stable config label used in logs and as the fresh combined-id prefix. */
+        id: string;
+        /** Optional stable identity; remounts resume its materialized history, while first use creates it fresh. */
+        sessionId?: SessionId;
+        /** Optional workspace for a fresh session. */
+        cwd?: string;
+        /** Persisted session to resume instead of creating a fresh session. */
+        resumeSessionId?: SessionId;
+    })[];
+}
+/** Agent-loop configuration after defaults and load-time validation. */
+type ResolvedConfig = Config & {
+    maxParallelToolCalls: number;
+};
+/** Concrete agent factory and driver service. */
+export declare class AgentLoop extends Service implements AgentFactory {
+    static inject: string[];
+    /** Runtime schema for declarative agents. */
+    static Config: z<Config>;
+    /** Validated configuration owned by the agent-loop service. */
+    readonly config: ResolvedConfig;
+    private readonly ownership;
+    /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */
+    private readonly runtime;
+    constructor(ctx: Context, config: Config);
+    /** Report a contained declarative-start failure to identity-bound consumers. */
+    private reportConfiguredStartupFailure;
+    /** Restore a materialized exact config identity on remount, or create it on first use. */
+    private restoreOrCreateConfigured;
+    /** Wait for a draining same-id lifecycle to finish registry teardown. */
+    private waitForDrainingConfiguredIdentity;
+    /**
+     * Construct the driver, scope, and one memoized reverse teardown for a new
+     * agent. The teardown is registered with the factory and the owner fiber
+     * BEFORE publication, so a mid-setup unload rolls everything back; `signal`
+     * fuses caller cancellation with lifecycle teardown for setup awaits.
+     */
+    private prepare;
+    /**
+     * Create an agent and session under one caller-supplied identity, owned by
+     * the accessing fiber. Constructor-driven config calls mint a fresh combined
+     * id before entering this boundary.
+     * @param id - shared agent/session identity.
+     * @param options - concrete loop options.
+     * @param meta - optional fresh-session workspace metadata.
+     * @returns the published running agent.
+     */
+    create(id: SessionId, options?: AgentOptions, meta?: Pick<SessionHeader, 'cwd'>): Agent;
+    /**
+     * Create an owned agent on a caller-supplied session id.
+     * @param ownerCtx - caller context that structurally owns the lifecycle.
+     * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>;
+    /** Prepare one Agent around an acquired Session, run setup, and publish it. */
+    private setupAndPublish;
+    /**
+     * Resume an owned agent from the configured persistence service.
+     * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+     * @param options - persisted identity, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;
+    /** Resume through an explicit persistence handle used by the deferred config path. */
+    private resumeWith;
+}
+export default AgentLoop;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned request-reconstruction invariant for loop-built LLM calls.
+ * @module @stackstackstack/dsh-agent-loop/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "agent-loop-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the agent-loop invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/runtime-context.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Durable projection state for dynamic runtime context.
+ * @module @stackstackstack/dsh-agent-loop/runtime-context
+ */
+import type { ContextSnapshotSection } from '@stackstackstack/dsh-llm';
+import type { Session, UserMessage } from '@stackstackstack/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+/** Tracks the last retained runtime-context snapshot without owning its commit. */
+export declare class RuntimeContextProjection {
+    /** `undefined` means no snapshot ever existed; `null` means none is retained. */
+    private retained;
+    /**
+     * Restore projection state once, then follow authoritative session events.
+     * @param ctx - agent-scoped event context.
+     * @param session - session receiving projected messages.
+     */
+    constructor(ctx: Context, session: Session);
+    /**
+     * Create an uncommitted snapshot only when the retained value differs.
+     * @param current - fully rendered dynamic context.
+     * @param sections - named contributions that formed the current snapshot.
+     * @returns a candidate user message, or `undefined` when no update is needed.
+     */
+    project(current: string, sections: readonly ContextSnapshotSection[]): UserMessage | undefined;
+}
+//# sourceMappingURL=runtime-context.d.ts.map

package/lib/types/tool-calls.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Schedules one assistant step's tool calls. Exclusive calls form barriers;
+ * parallel calls use a bounded rolling pool and are reclassified before start.
+ * Dispatch may overlap, while policy, results, and result context remain
+ * model-ordered. Abort or an internal scheduler failure stops replenishment
+ * and drains started calls.
+ *
+ * Abort records synthetic error results for skipped calls so replay stays
+ * valid. A terminal scheduler failure preserves already-recorded `tool/call`
+ * events without fabricating results.
+ * @module dsh-agent-loop/tool-calls
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ToolCallBlock } from '@stackstackstack/dsh-llm';
+import type { UserMessage } from '@stackstackstack/dsh-session';
+/**
+ * Schedule one assistant step's tool calls by their live concurrency mode.
+ * Ordinary completion and abort commit started-call results in order. Abort
+ * drains them, records synthetic results for unstarted calls, and returns with
+ * the signal still aborted after accepting started-call context through the
+ * caller-supplied acceptor (the machine stages it in its next-step inbox for the
+ * step boundary). An internal scheduler failure stops new dispatches, drains
+ * already-started dispatches, and rejects with the first failure without
+ * fabricating tool results.
+ * The committed step's AgentLoop driver boundary supplies the initiating Agent
+ * that becomes each explicit {@link ToolExecutionInput.agent}.
+ *
+ * @param ctx - loop context that owns the tool registry and carries the initiating Agent.
+ * @param turn - current turn number.
+ * @param step - current step number.
+ * @param toolCalls - assistant calls in model order.
+ * @param signal - abort signal shared by the step.
+ * @param acceptContext - accepts committed result context for the next step boundary.
+ */
+export declare function executeToolCalls(ctx: Context, turn: number, step: number, toolCalls: ToolCallBlock[], signal: AbortSignal, acceptContext: (context: UserMessage) => void): Promise<{
+    concluded: boolean;
+}>;
+//# sourceMappingURL=tool-calls.d.ts.map

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@stackstackstack/dsh-agent-loop",
+  "description": "The concrete agent loop plugin for the DeepSeek Harness",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/core/agent-loop"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-scope": "^0.1.5",
+    "@stackstackstack/dsh-llm": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-system-prompt": "^0.1.5",
+    "@stackstackstack/dsh-settings": "^0.1.5",
+    "@stackstackstack/dsh-tools": "^0.1.5",
+    "@stackstackstack/dsh-session-persistence": "^0.1.5"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-llm": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-scope": "^0.1.5",
+    "@stackstackstack/dsh-session-persistence": "^0.1.5",
+    "@stackstackstack/dsh-system-prompt": "^0.1.5",
+    "@stackstackstack/dsh-tools": "^0.1.5",
+    "@stackstackstack/dsh-settings": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@stackstackstack/dsh-session-persistence-jsonl": "^0.1.5"
+  }
+}