@deepstrike/sdk 0.1.10 → 0.1.12

package/README.md

@@ -50,6 +50,15 @@ const result = await agent.run("What is 17 + 28?")
 console.log(result)
 ```
 
+Same-session conversation continuity is explicit via `sessionId`:
+
+```typescript
+await agent.run("My name is Ada.", undefined, undefined, "chat-1")
+const reply = await agent.run("What is my name?", undefined, undefined, "chat-1")
+```
+
+By default, the agent keeps session transcripts in memory for the lifetime of that `Agent` instance. Provide a `sessionStore` when the transcript must survive process restarts or be shared across workers.
+
 Streaming:
 
 ```typescript
@@ -196,6 +205,22 @@ const agent = new Agent(provider, {
 const result = await agent.dream("my-agent", Date.now())
 ```
 
+### SessionStore (same-session transcript continuity)
+
+```typescript
+import type { SessionStore } from "@deepstrike/sdk"
+
+class MySessionStore implements SessionStore {
+  async loadSession(sessionId) { return db.sessions.get(sessionId) }
+  async saveSession(session) { await db.sessions.put(session.sessionId, session) }
+}
+
+const agent = new Agent(provider, {
+  maxTokens: 4096,
+  sessionStore: new MySessionStore(),
+})
+```
+
 ---
 
 ## Governance

package/dist/agent.d.ts

@@ -1,6 +1,6 @@
 import type { LLMProvider, StreamEvent } from "./types.js";
 import type { RegisteredTool } from "./tools/index.js";
-import type { DreamStore, DreamResult } from "./memory/protocols.js";
+import type { DreamStore, DreamResult, SessionStore } from "./memory/protocols.js";
 import type { KnowledgeSource } from "./knowledge/source.js";
 import type { SignalSource } from "./signals/types.js";
 export interface AgentOptions {
@@ -13,12 +13,6 @@ export interface AgentOptions {
      * Passed to the kernel's `system` partition before the first LLM call.
      */
     systemPrompt?: string;
-    /**
-     * Long-term memory snippets pre-seeded into the context before the first LLM call.
-     * Each string is pushed to the kernel's `memory` partition (highest-priority context
-     * after system). Use to inject memories retrieved from a DreamStore before a run.
-     */
-    initialMemory?: string[];
     /**
      * Directory containing skill `.md` files. The kernel auto-injects a `skill`
      * meta-tool so the model can load any skill by name on demand.
@@ -28,6 +22,8 @@ export interface AgentOptions {
     signalSource?: SignalSource;
     /** Backing store for the idle dreaming pipeline. Required to call `Agent.dream()`. */
     dreamStore?: DreamStore;
+    /** Optional durable transcript store for same-session conversational continuity. */
+    sessionStore?: SessionStore;
     /**
      * Stable identifier for this agent. Required to enable in-session memory retrieval
      * when `dreamStore` is configured.
@@ -56,6 +52,7 @@ export declare class Agent {
     private knowledgeSource?;
     private signalSource?;
     private dreamStore?;
+    private readonly inMemorySessions;
     private interrupted;
     private pendingInterrupt;
     private _turn;
@@ -72,8 +69,12 @@ export declare class Agent {
      * Collect the full text response and return it.
      * For richer control (streaming, tool events, token counts) use `runStreaming`.
      */
-    run(goal: string, criteria?: string[], extensions?: Record<string, unknown>): Promise<string>;
-    runStreaming(goal: string, criteria?: string[], extensions?: Record<string, unknown>): AsyncIterable<StreamEvent>;
+    run(goal: string, criteria?: string[], extensions?: Record<string, unknown>, sessionId?: string): Promise<string>;
+    runStreaming(goal: string, criteria?: string[], extensions?: Record<string, unknown>, sessionId?: string): AsyncIterable<StreamEvent>;
+    private loadSession;
+    private saveSession;
+    private toMessage;
+    private kernelMsgToSessionMsg;
     /**
      * Trigger the idle dreaming cycle for this agent.
      * Requires `dreamStore` and `agentId` to be configured.

package/dist/agent.js

@@ -10,6 +10,7 @@ export class Agent {
     knowledgeSource;
     signalSource;
     dreamStore;
+    inMemorySessions = new Map();
     interrupted = false;
     pendingInterrupt = false;
     // Live telemetry — updated each runStreaming call
@@ -44,15 +45,15 @@ export class Agent {
      * Collect the full text response and return it.
      * For richer control (streaming, tool events, token counts) use `runStreaming`.
      */
-    async run(goal, criteria, extensions) {
+    async run(goal, criteria, extensions, sessionId) {
         let content = "";
-        for await (const evt of this.runStreaming(goal, criteria, extensions)) {
+        for await (const evt of this.runStreaming(goal, criteria, extensions, sessionId)) {
             if (evt.type === "text_delta")
                 content += evt.delta;
         }
         return content;
     }
-    async *runStreaming(goal, criteria, extensions) {
+    async *runStreaming(goal, criteria, extensions, sessionId) {
         this.interrupted = false;
         this.pendingInterrupt = false;
         this._turn = 0;
@@ -76,8 +77,10 @@ export class Agent {
             const tokens = Math.max(1, Math.ceil(this.options.systemPrompt.length / 4));
             sm.addSystemMessage(this.options.systemPrompt, tokens);
         }
-        for (const mem of this.options.initialMemory ?? []) {
-            sm.addMemoryMessage(mem, Math.max(1, Math.ceil(mem.length / 4)));
+        const previousSession = sessionId ? await this.loadSession(sessionId) : undefined;
+        const previousMsgs = previousSession?.messages ?? [];
+        if (previousMsgs.length > 0) {
+            sm.preloadHistory(previousMsgs.map(m => this.toMessage(m)));
         }
         if (this.skillDir) {
             const skillMetas = await scanSkillDir(this.skillDir);
@@ -97,7 +100,6 @@ export class Agent {
         }
         let action = sm.start({ goal, criteria: criteria ?? [] });
         const sessionStart = Date.now();
-        const sessionMsgs = [{ role: "user", content: goal }];
         while (!sm.isTerminal()) {
             // Update telemetry
             this._turn = sm.turn;
@@ -153,11 +155,11 @@ export class Agent {
             if (action.kind === "call_llm") {
                 const finalToolCalls = [];
                 let finalText = "";
-                const messages = (action.messages ?? []);
+                const context = action.context;
                 const tools = (action.tools ?? []);
                 let turnTokens = 0;
                 try {
-                    for await (const evt of this.provider.stream(messages, tools, Object.keys(ext).length ? ext : undefined, providerState)) {
+                    for await (const evt of this.provider.stream(context, tools, Object.keys(ext).length ? ext : undefined, providerState)) {
                         if (evt.type === "usage") {
                             turnTokens = evt.totalTokens;
                             continue;
@@ -177,7 +179,6 @@ export class Agent {
                     break;
                 }
                 action = sm.feedLlmResponse({ role: "assistant", content: finalText, toolCalls: finalToolCalls, tokenCount: turnTokens || undefined });
-                sessionMsgs.push({ role: "assistant", content: finalText, toolCalls: finalToolCalls });
             }
             else if (action.kind === "execute_tools") {
                 const allCalls = action.calls ?? [];
@@ -266,12 +267,13 @@ export class Agent {
         this._pressure = sm.pressure();
         const status = result?.termination ?? "error";
         const iterations = result ? Math.max(1, result.turnsUsed) : 0;
-        if (this.options.dreamStore && this.options.agentId && sessionMsgs.length > 1) {
+        const newMsgs = sm.drainNewMessages().map(m => this.kernelMsgToSessionMsg(m));
+        if (this.options.dreamStore && this.options.agentId && newMsgs.length > 0) {
             try {
                 await this.options.dreamStore.saveSession({
                     sessionId: crypto.randomUUID(),
                     agentId: this.options.agentId,
-                    messages: sessionMsgs,
+                    messages: newMsgs,
                     metadata: null,
                     createdAtMs: sessionStart,
                     updatedAtMs: Date.now(),
@@ -279,6 +281,17 @@ export class Agent {
             }
             catch { /* session save failure must not surface to caller */ }
         }
+        if (sessionId) {
+            const now = Date.now();
+            await this.saveSession({
+                sessionId,
+                agentId: this.options.agentId ?? "default",
+                messages: [...previousMsgs, ...newMsgs],
+                metadata: previousSession?.metadata ?? null,
+                createdAtMs: previousSession?.createdAtMs ?? sessionStart,
+                updatedAtMs: now,
+            });
+        }
         yield {
             type: "done",
             iterations,
@@ -286,6 +299,36 @@ export class Agent {
             status,
         };
     }
+    async loadSession(sessionId) {
+        return this.options.sessionStore
+            ? this.options.sessionStore.loadSession(sessionId)
+            : this.inMemorySessions.get(sessionId);
+    }
+    async saveSession(data) {
+        if (this.options.sessionStore) {
+            await this.options.sessionStore.saveSession(data);
+            return;
+        }
+        this.inMemorySessions.set(data.sessionId, data);
+    }
+    toMessage(message) {
+        return {
+            role: message.role,
+            content: message.content,
+            contentParts: message.contentParts,
+            tokenCount: message.tokenCount,
+            toolCalls: message.toolCalls ?? [],
+        };
+    }
+    kernelMsgToSessionMsg(msg) {
+        return {
+            role: msg.role,
+            content: msg.content,
+            contentParts: msg.contentParts,
+            tokenCount: msg.tokenCount,
+            toolCalls: msg.toolCalls?.length ? msg.toolCalls : undefined,
+        };
+    }
     /**
      * Trigger the idle dreaming cycle for this agent.
      * Requires `dreamStore` and `agentId` to be configured.
@@ -332,7 +375,16 @@ export class Agent {
         }
         let synthesisText = "";
         const providerState = this.provider.createRunState?.();
-        for await (const evt of this.provider.stream((action1.messages ?? []), [], undefined, providerState)) {
+        // IdlePipeline produces raw messages for synthesis; wrap them in a RenderedContext.
+        // The first system message (if any) becomes systemText; the rest are turns.
+        const synthMsgs = (action1.messages ?? []);
+        const synthSystemMsgs = synthMsgs.filter(m => m.role === "system");
+        const synthTurns = synthMsgs.filter(m => m.role !== "system");
+        const synthContext = {
+            systemText: synthSystemMsgs.map(m => m.content).join("\n\n"),
+            turns: synthTurns,
+        };
+        for await (const evt of this.provider.stream(synthContext, [], undefined, providerState)) {
             if (evt.type === "text_delta")
                 synthesisText += evt.delta;
         }

package/dist/collaboration/contract.d.ts

@@ -0,0 +1,55 @@
+/**
+ * VerificationContract — first-class type for contract-driven development.
+ *
+ * Contracts travel in the executor's system partition (never compressed) and
+ * are given to the verifier alongside the artifact. The verifier never sees
+ * the executor's implementation history — only the goal, contract, and artifact.
+ */
+export interface AcceptanceCriterion {
+    /** Stable id — matched in ContractCheckResult. */
+    id: string;
+    /** Human-readable statement of what correct looks like. */
+    text: string;
+    /** If true, failure here fails the entire contract regardless of score. */
+    required: boolean;
+    /** Contribution to the weighted overall score [0.0–1.0]. */
+    weight: number;
+    /** If true the SDK can verify this deterministically (e.g. word count, schema). */
+    machineCheckable: boolean;
+}
+export interface VerificationContract {
+    /** Stable id — doubles as the skill name on successful extraction. */
+    id: string;
+    /** Goal this contract governs. Injected into the executor's context. */
+    goal: string;
+    acceptance: AcceptanceCriterion[];
+    /** Patterns the executor must avoid. Checked by the verifier. */
+    antiPatterns: string[];
+    /** Artifacts that must be present before the verifier runs. */
+    evidenceRequired: string[];
+}
+export interface ContractCheckResult {
+    criterionId: string;
+    passed: boolean;
+    evidence?: string;
+}
+/** Build a contract incrementally. */
+export declare class ContractBuilder {
+    private contract;
+    constructor(id: string, goal: string);
+    criterion(id: string, text: string, opts?: {
+        required?: boolean;
+        weight?: number;
+        machineCheckable?: boolean;
+    }): this;
+    antiPattern(pattern: string): this;
+    evidence(item: string): this;
+    build(): VerificationContract;
+}
+/**
+ * Render the contract as a markdown block for injection into a system prompt.
+ * Used by ContractDrivenHarness to inject into the executor's system partition.
+ */
+export declare function formatContractForSystemPrompt(contract: VerificationContract): string;
+/** Derive a flat string[] of criterion texts for the existing HarnessLoop criteria API. */
+export declare function contractToCriteriaStrings(contract: VerificationContract): string[];

package/dist/collaboration/contract.js

@@ -0,0 +1,65 @@
+/**
+ * VerificationContract — first-class type for contract-driven development.
+ *
+ * Contracts travel in the executor's system partition (never compressed) and
+ * are given to the verifier alongside the artifact. The verifier never sees
+ * the executor's implementation history — only the goal, contract, and artifact.
+ */
+/** Build a contract incrementally. */
+export class ContractBuilder {
+    contract;
+    constructor(id, goal) {
+        this.contract = { id, goal, acceptance: [], antiPatterns: [], evidenceRequired: [] };
+    }
+    criterion(id, text, opts = {}) {
+        this.contract.acceptance.push({
+            id,
+            text,
+            required: opts.required ?? true,
+            weight: Math.min(1, Math.max(0, opts.weight ?? 1.0)),
+            machineCheckable: opts.machineCheckable ?? false,
+        });
+        return this;
+    }
+    antiPattern(pattern) {
+        this.contract.antiPatterns.push(pattern);
+        return this;
+    }
+    evidence(item) {
+        this.contract.evidenceRequired.push(item);
+        return this;
+    }
+    build() {
+        return structuredClone(this.contract);
+    }
+}
+/**
+ * Render the contract as a markdown block for injection into a system prompt.
+ * Used by ContractDrivenHarness to inject into the executor's system partition.
+ */
+export function formatContractForSystemPrompt(contract) {
+    const lines = [
+        `## Verification Contract: ${contract.id}`,
+        "",
+        `Goal: ${contract.goal}`,
+        "",
+        "### Acceptance Criteria",
+    ];
+    contract.acceptance.forEach((c, i) => {
+        const req = c.required ? "[REQUIRED]" : "[OPTIONAL]";
+        lines.push(`${i + 1}. ${req} ${c.text} (id: \`${c.id}\`, weight: ${c.weight.toFixed(1)})`);
+    });
+    if (contract.antiPatterns.length > 0) {
+        lines.push("", "### Anti-Patterns (must avoid)");
+        contract.antiPatterns.forEach(p => lines.push(`- ${p}`));
+    }
+    if (contract.evidenceRequired.length > 0) {
+        lines.push("", "### Required Evidence");
+        contract.evidenceRequired.forEach(e => lines.push(`- ${e}`));
+    }
+    return lines.join("\n");
+}
+/** Derive a flat string[] of criterion texts for the existing HarnessLoop criteria API. */
+export function contractToCriteriaStrings(contract) {
+    return contract.acceptance.map(c => c.text);
+}

package/dist/collaboration/handoff.d.ts

@@ -0,0 +1,79 @@
+import type { ContractCheckResult, VerificationContract } from "./contract.js";
+import type { DreamResult } from "../memory/protocols.js";
+/**
+ * HandoffArtifact — the single exchange token between sprints and agent instances.
+ *
+ * All handoff paths converge here:
+ *   - ContractDrivenHarness completion  → HandoffBus.fromContractOutcome()
+ *   - Sub-agent completion              → HandoffBus.fromSubAgentResult()
+ *   - Dream consolidation               → HandoffBus.fromDream()
+ *   - Context renewal (kernel)          → carried in kernel's HandoffArtifact type
+ *
+ * The invariant: a HandoffArtifact tells the next agent not only *what was done*
+ * but *what has been proven*. The contract_status field is never discarded on renewal.
+ */
+export interface HandoffArtifact {
+    goal: string;
+    sprint: number;
+    progressSummary: string;
+    openTasks: string[];
+    /** Per-criterion verification results from the most recent contract run. */
+    contractStatus: ContractCheckResult[];
+    /** Ratio of verification failures over 24 h (failed / total). 0.0 if no data. */
+    driftRate24h: number;
+    /** Issues blocking completion — require human or orchestrator attention. */
+    blockedOn: string[];
+}
+/** Input to HandoffBus.fromContractOutcome */
+export interface ContractOutcomeInput {
+    contract: VerificationContract;
+    checkResults: ContractCheckResult[];
+    artifact: string;
+    success: boolean;
+    blockedOn?: string[];
+}
+/**
+ * HandoffBus — the canonical factory for HandoffArtifact.
+ *
+ * Every transition between agent contexts goes through one of these static methods.
+ * This ensures that the resulting artifact always carries contract_status, never just
+ * a prose summary.
+ */
+export declare class HandoffBus {
+    /**
+     * Build a HandoffArtifact from a ContractDrivenHarness outcome.
+     * The artifact field is used as the progress summary.
+     */
+    static fromContractOutcome(input: ContractOutcomeInput): HandoffArtifact;
+    /**
+     * Build a HandoffArtifact from a sub-agent's final message.
+     * Matches the convention established by `report_sub_agent` (only final message injected).
+     */
+    static fromSubAgentResult(opts: {
+        goal: string;
+        finalMessage: string;
+        sprint?: number;
+    }): HandoffArtifact;
+    /**
+     * Build a HandoffArtifact from a dream consolidation result.
+     * Used when the idle pipeline produces new memories that should be
+     * carried into the next sprint's context.
+     */
+    static fromDream(opts: {
+        goal: string;
+        dreamResult: DreamResult;
+        sprint?: number;
+    }): HandoffArtifact;
+    /**
+     * Render the artifact as a compact injection string for the next agent's
+     * working partition (not system — this is a handoff note, not a permanent rule).
+     */
+    static toContextNote(artifact: HandoffArtifact): string;
+    /**
+     * True when drift rate exceeds threshold or required criteria are blocked.
+     * Use to decide whether to pause autonomous delegation and escalate.
+     */
+    static requiresEscalation(artifact: HandoffArtifact, opts?: {
+        driftThreshold?: number;
+    }): boolean;
+}

package/dist/collaboration/handoff.js

@@ -0,0 +1,98 @@
+/**
+ * HandoffBus — the canonical factory for HandoffArtifact.
+ *
+ * Every transition between agent contexts goes through one of these static methods.
+ * This ensures that the resulting artifact always carries contract_status, never just
+ * a prose summary.
+ */
+export class HandoffBus {
+    /**
+     * Build a HandoffArtifact from a ContractDrivenHarness outcome.
+     * The artifact field is used as the progress summary.
+     */
+    static fromContractOutcome(input) {
+        const failedRequired = input.checkResults.filter(r => {
+            if (r.passed)
+                return false;
+            const c = input.contract.acceptance.find(a => a.id === r.criterionId);
+            return c?.required ?? false;
+        });
+        return {
+            goal: input.contract.goal,
+            sprint: 1,
+            progressSummary: input.success
+                ? `Completed: ${input.artifact.slice(0, 200)}${input.artifact.length > 200 ? "…" : ""}`
+                : `Incomplete after max attempts. ${failedRequired.length} required criteria failed.`,
+            openTasks: input.success ? [] : failedRequired.map(r => `Fix criterion: ${r.criterionId}`),
+            contractStatus: input.checkResults,
+            driftRate24h: input.checkResults.length > 0
+                ? input.checkResults.filter(r => !r.passed).length / input.checkResults.length
+                : 0,
+            blockedOn: input.blockedOn ?? [],
+        };
+    }
+    /**
+     * Build a HandoffArtifact from a sub-agent's final message.
+     * Matches the convention established by `report_sub_agent` (only final message injected).
+     */
+    static fromSubAgentResult(opts) {
+        return {
+            goal: opts.goal,
+            sprint: opts.sprint ?? 1,
+            progressSummary: opts.finalMessage.slice(0, 500),
+            openTasks: [],
+            contractStatus: [],
+            driftRate24h: 0,
+            blockedOn: [],
+        };
+    }
+    /**
+     * Build a HandoffArtifact from a dream consolidation result.
+     * Used when the idle pipeline produces new memories that should be
+     * carried into the next sprint's context.
+     */
+    static fromDream(opts) {
+        return {
+            goal: opts.goal,
+            sprint: opts.sprint ?? 1,
+            progressSummary: `Memory consolidated: ${opts.dreamResult.entriesAdded} added, ${opts.dreamResult.entriesRemoved} removed.`,
+            openTasks: [],
+            contractStatus: [],
+            driftRate24h: 0,
+            blockedOn: [],
+        };
+    }
+    /**
+     * Render the artifact as a compact injection string for the next agent's
+     * working partition (not system — this is a handoff note, not a permanent rule).
+     */
+    static toContextNote(artifact) {
+        const lines = [
+            `[Handoff from sprint ${artifact.sprint}]`,
+            `Goal: ${artifact.goal}`,
+            `Progress: ${artifact.progressSummary}`,
+        ];
+        if (artifact.openTasks.length > 0) {
+            lines.push(`Open tasks: ${artifact.openTasks.join("; ")}`);
+        }
+        if (artifact.contractStatus.length > 0) {
+            const passed = artifact.contractStatus.filter(r => r.passed).length;
+            lines.push(`Contract: ${passed}/${artifact.contractStatus.length} criteria passed`);
+        }
+        if (artifact.blockedOn.length > 0) {
+            lines.push(`BLOCKED ON: ${artifact.blockedOn.join("; ")}`);
+        }
+        if (artifact.driftRate24h > 0) {
+            lines.push(`Drift rate: ${(artifact.driftRate24h * 100).toFixed(1)}%`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * True when drift rate exceeds threshold or required criteria are blocked.
+     * Use to decide whether to pause autonomous delegation and escalate.
+     */
+    static requiresEscalation(artifact, opts = {}) {
+        const threshold = opts.driftThreshold ?? 0.05;
+        return artifact.driftRate24h > threshold || artifact.blockedOn.length > 0;
+    }
+}

package/dist/collaboration/harness.d.ts

@@ -0,0 +1,55 @@
+import type { AgentPool } from "./pool.js";
+import type { VerificationContract, ContractCheckResult } from "./contract.js";
+import type { HandoffArtifact } from "./handoff.js";
+export interface Violation {
+    criterionId: string;
+    text: string;
+    detail: string;
+}
+export interface ContractOutcome {
+    success: boolean;
+    artifact: string;
+    checkResults: ContractCheckResult[];
+    attemptsUsed: number;
+    totalTokensConsumed: number;
+    handoff: HandoffArtifact;
+}
+export interface ContractHarnessOptions {
+    maxAttempts?: number;
+    onViolation?: (violations: Violation[]) => void;
+}
+/**
+ * ContractDrivenHarness — the core multi-agent execution primitive.
+ *
+ * Differs from HarnessLoop in three ways:
+ *   1. Executor and verifier are **separate Agent instances** — no shared history.
+ *   2. Verifier receives only the artifact + contract, not the implementation transcript.
+ *   3. Feedback returned to the executor is a structured list of Violations,
+ *      not a free-text LLM summary.
+ *
+ * Protocol per attempt:
+ *   executor.run(goal, contract) → artifact
+ *   verifier.runIsolated(artifact, contract) → audit text
+ *   parse audit text → ContractCheckResult[]
+ *   all required criteria pass → Done
+ *   violations remain → inject only violation list into next executor goal
+ *   maxAttempts exceeded → produce HandoffArtifact with blocked_on
+ */
+export declare class ContractDrivenHarness {
+    private pool;
+    private contract;
+    private maxAttempts;
+    private onViolation?;
+    constructor(pool: AgentPool, contract: VerificationContract, options?: ContractHarnessOptions);
+    run(): Promise<ContractOutcome>;
+    private _findViolations;
+    private _formatViolationsForFeedback;
+    /**
+     * Parse the verifier's free-text audit into structured ContractCheckResult[].
+     *
+     * The verifier is prompted to produce a structured PASS/FAIL per criterion.
+     * This parser handles the common patterns; callers can subclass and override
+     * for stricter parsing.
+     */
+    private _parseAuditText;
+}