@deepstrike/sdk 0.1.9 → 0.1.11

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;
+}

package/dist/collaboration/harness.js

@@ -0,0 +1,150 @@
+import { formatContractForSystemPrompt, contractToCriteriaStrings } from "./contract.js";
+import { HandoffBus } from "./handoff.js";
+/**
+ * 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 class ContractDrivenHarness {
+    pool;
+    contract;
+    maxAttempts;
+    onViolation;
+    constructor(pool, contract, options = {}) {
+        this.pool = pool;
+        this.contract = contract;
+        this.maxAttempts = options.maxAttempts ?? 3;
+        this.onViolation = options.onViolation;
+    }
+    async run() {
+        let artifact = "";
+        let checkResults = [];
+        let attemptsUsed = 0;
+        let currentGoal = this.contract.goal;
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            attemptsUsed = attempt;
+            // ── Phase 1: Executor ──────────────────────────────────────────────────
+            // Executor sees: contract block + goal. No verifier history.
+            const contractBlock = formatContractForSystemPrompt(this.contract);
+            const violationNote = attempt > 1
+                ? `\n\n[Previous attempt failed. Violations to fix:\n${this._formatViolationsForFeedback(checkResults)}]`
+                : "";
+            const executorGoal = `${contractBlock}\n\n---\n\n${currentGoal}${violationNote}`;
+            artifact = await this.pool.get("executor").run(executorGoal, contractToCriteriaStrings(this.contract));
+            // ── Phase 2: Verifier ──────────────────────────────────────────────────
+            // Verifier sees: artifact + contract only. No executor history.
+            const auditText = await this.pool.runVerifier({ contract: this.contract, artifact });
+            // ── Phase 3: Parse audit → ContractCheckResult[] ──────────────────────
+            checkResults = this._parseAuditText(auditText);
+            const violations = this._findViolations(checkResults);
+            if (violations.length === 0) {
+                // All required criteria passed
+                return {
+                    success: true,
+                    artifact,
+                    checkResults,
+                    attemptsUsed,
+                    totalTokensConsumed: 0,
+                    handoff: HandoffBus.fromContractOutcome({
+                        contract: this.contract,
+                        checkResults,
+                        artifact,
+                        success: true,
+                    }),
+                };
+            }
+            this.onViolation?.(violations);
+        }
+        // Max attempts exhausted
+        const blockedOn = this._findViolations(checkResults).map(v => `[${v.criterionId}] ${v.text}: ${v.detail}`);
+        return {
+            success: false,
+            artifact,
+            checkResults,
+            attemptsUsed,
+            totalTokensConsumed: 0,
+            handoff: HandoffBus.fromContractOutcome({
+                contract: this.contract,
+                checkResults,
+                artifact,
+                success: false,
+                blockedOn,
+            }),
+        };
+    }
+    _findViolations(results) {
+        const violations = [];
+        for (const result of results) {
+            if (!result.passed) {
+                const criterion = this.contract.acceptance.find(c => c.id === result.criterionId);
+                if (criterion?.required) {
+                    violations.push({
+                        criterionId: result.criterionId,
+                        text: criterion.text,
+                        detail: result.evidence ?? "no evidence provided",
+                    });
+                }
+            }
+        }
+        return violations;
+    }
+    _formatViolationsForFeedback(results) {
+        return this._findViolations(results)
+            .map(v => `- [${v.criterionId}] ${v.text}: ${v.detail}`)
+            .join("\n");
+    }
+    /**
+     * 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.
+     */
+    _parseAuditText(auditText) {
+        const results = [];
+        const lower = auditText.toLowerCase();
+        for (const criterion of this.contract.acceptance) {
+            // Look for explicit "id: PASS" or "id: FAIL" patterns from the verifier prompt
+            const idPattern = new RegExp(`\\b${criterion.id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b[^\\n]*?(pass|fail)`, "i");
+            const match = auditText.match(idPattern);
+            if (match) {
+                const passed = match[1].toLowerCase() === "pass";
+                // Extract the line as evidence
+                const lineStart = auditText.lastIndexOf("\n", match.index ?? 0) + 1;
+                const lineEnd = auditText.indexOf("\n", match.index ?? 0);
+                const evidence = auditText.slice(lineStart, lineEnd > 0 ? lineEnd : undefined).trim();
+                results.push({ criterionId: criterion.id, passed, evidence });
+            }
+            else {
+                // Fallback: search for criterion text near PASS/FAIL keywords
+                const textIdx = lower.indexOf(criterion.text.toLowerCase().slice(0, 30));
+                if (textIdx !== -1) {
+                    const window = lower.slice(textIdx, textIdx + 200);
+                    const passed = window.includes("pass") && !window.includes("fail");
+                    results.push({ criterionId: criterion.id, passed, evidence: "inferred from context" });
+                }
+                else {
+                    // No mention found — conservative: treat as failed
+                    results.push({
+                        criterionId: criterion.id,
+                        passed: false,
+                        evidence: "criterion not mentioned in audit",
+                    });
+                }
+            }
+        }
+        return results;
+    }
+}

package/dist/collaboration/index.d.ts

@@ -0,0 +1,10 @@
+export type { AcceptanceCriterion, VerificationContract, ContractCheckResult, } from "./contract.js";
+export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings, } from "./contract.js";
+export { AgentPool } from "./pool.js";
+export type { AgentRole, IsolatedVerifierContext } from "./pool.js";
+export { ContractDrivenHarness } from "./harness.js";
+export type { ContractOutcome, ContractHarnessOptions, Violation, } from "./harness.js";
+export { HandoffBus } from "./handoff.js";
+export type { HandoffArtifact, ContractOutcomeInput } from "./handoff.js";
+export { CreatorVerifierMode, OrchestrationMode } from "./modes/creator-verifier.js";
+export type { CreatorVerifierMetrics } from "./modes/creator-verifier.js";

package/dist/collaboration/index.js

@@ -0,0 +1,9 @@
+export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings, } from "./contract.js";
+// AgentPool
+export { AgentPool } from "./pool.js";
+// ContractDrivenHarness
+export { ContractDrivenHarness } from "./harness.js";
+// HandoffBus
+export { HandoffBus } from "./handoff.js";
+// Collaboration modes
+export { CreatorVerifierMode, OrchestrationMode } from "./modes/creator-verifier.js";

package/dist/collaboration/modes/creator-verifier.d.ts

@@ -0,0 +1,69 @@
+import type { AgentPool } from "../pool.js";
+import type { VerificationContract } from "../contract.js";
+import type { ContractOutcome } from "../harness.js";
+export interface CreatorVerifierMetrics {
+    total: number;
+    failed: number;
+    driftRate: number;
+}
+/**
+ * CreatorVerifierMode — the simplest multi-agent collaboration pattern.
+ *
+ * Wires an executor + verifier from an AgentPool into a ContractDrivenHarness.
+ * The executor creates, the verifier audits. Contexts are fully isolated.
+ *
+ * Usage:
+ * ```ts
+ * const pool = new AgentPool()
+ *   .add("executor", new Agent(provider, { maxTokens: 32_000, skillDir }))
+ *   .add("verifier", new Agent(provider, { maxTokens: 8_000 }))
+ *
+ * const mode = new CreatorVerifierMode(pool)
+ * const result = await mode.run(contract)
+ *
+ * if (HandoffBus.requiresEscalation(result.handoff)) {
+ *   // drift > 5% or blocked_on is non-empty → pause autonomous delegation
+ * }
+ * ```
+ */
+export declare class CreatorVerifierMode {
+    private pool;
+    private options;
+    private _total;
+    private _failed;
+    constructor(pool: AgentPool, options?: {
+        maxAttempts?: number;
+    });
+    run(contract: VerificationContract): Promise<ContractOutcome>;
+    /** Aggregate drift metrics across all runs through this mode instance. */
+    getMetrics(): CreatorVerifierMetrics;
+    /**
+     * True when accumulated drift rate exceeds threshold.
+     * When true, pause autonomous delegation and surface to human or orchestrator.
+     */
+    isDrifting(threshold?: number): boolean;
+    /** Reset accumulated metrics (e.g. at the start of a new sprint). */
+    resetMetrics(): void;
+}
+/**
+ * OrchestrationMode — three-role collaboration: orchestrator → executor → verifier.
+ *
+ * The orchestrator produces a VerificationContract from a raw goal, then
+ * CreatorVerifierMode executes it.
+ *
+ * Requires all three roles in the pool: orchestrator, executor, verifier.
+ */
+export declare class OrchestrationMode {
+    private pool;
+    private options;
+    private inner;
+    constructor(pool: AgentPool, options?: {
+        maxAttempts?: number;
+    });
+    run(goal: string): Promise<ContractOutcome & {
+        contract: VerificationContract;
+    }>;
+    getMetrics(): CreatorVerifierMetrics;
+    isDrifting(threshold?: number): boolean;
+    private _parseContract;
+}

package/dist/collaboration/modes/creator-verifier.js

@@ -0,0 +1,124 @@
+import { ContractDrivenHarness } from "../harness.js";
+/**
+ * CreatorVerifierMode — the simplest multi-agent collaboration pattern.
+ *
+ * Wires an executor + verifier from an AgentPool into a ContractDrivenHarness.
+ * The executor creates, the verifier audits. Contexts are fully isolated.
+ *
+ * Usage:
+ * ```ts
+ * const pool = new AgentPool()
+ *   .add("executor", new Agent(provider, { maxTokens: 32_000, skillDir }))
+ *   .add("verifier", new Agent(provider, { maxTokens: 8_000 }))
+ *
+ * const mode = new CreatorVerifierMode(pool)
+ * const result = await mode.run(contract)
+ *
+ * if (HandoffBus.requiresEscalation(result.handoff)) {
+ *   // drift > 5% or blocked_on is non-empty → pause autonomous delegation
+ * }
+ * ```
+ */
+export class CreatorVerifierMode {
+    pool;
+    options;
+    _total = 0;
+    _failed = 0;
+    constructor(pool, options = {}) {
+        this.pool = pool;
+        this.options = options;
+    }
+    async run(contract) {
+        this._total++;
+        const harness = new ContractDrivenHarness(this.pool, contract, {
+            maxAttempts: this.options.maxAttempts ?? 3,
+        });
+        const outcome = await harness.run();
+        if (!outcome.success) {
+            this._failed++;
+        }
+        return outcome;
+    }
+    /** Aggregate drift metrics across all runs through this mode instance. */
+    getMetrics() {
+        return {
+            total: this._total,
+            failed: this._failed,
+            driftRate: this._total > 0 ? this._failed / this._total : 0,
+        };
+    }
+    /**
+     * True when accumulated drift rate exceeds threshold.
+     * When true, pause autonomous delegation and surface to human or orchestrator.
+     */
+    isDrifting(threshold = 0.05) {
+        return this.getMetrics().driftRate > threshold;
+    }
+    /** Reset accumulated metrics (e.g. at the start of a new sprint). */
+    resetMetrics() {
+        this._total = 0;
+        this._failed = 0;
+    }
+}
+/**
+ * OrchestrationMode — three-role collaboration: orchestrator → executor → verifier.
+ *
+ * The orchestrator produces a VerificationContract from a raw goal, then
+ * CreatorVerifierMode executes it.
+ *
+ * Requires all three roles in the pool: orchestrator, executor, verifier.
+ */
+export class OrchestrationMode {
+    pool;
+    options;
+    inner;
+    constructor(pool, options = {}) {
+        this.pool = pool;
+        this.options = options;
+        this.inner = new CreatorVerifierMode(pool, options);
+    }
+    async run(goal) {
+        // Step 1: orchestrator produces a VerificationContract
+        const contractJson = await this.pool.runOrchestrator(goal);
+        const contract = this._parseContract(contractJson, goal);
+        // Step 2: CreatorVerifierMode executes against the contract
+        const outcome = await this.inner.run(contract);
+        return { ...outcome, contract };
+    }
+    getMetrics() {
+        return this.inner.getMetrics();
+    }
+    isDrifting(threshold = 0.05) {
+        return this.inner.isDrifting(threshold);
+    }
+    _parseContract(json, fallbackGoal) {
+        try {
+            // Extract JSON block from markdown fences if present
+            const match = json.match(/```(?:json)?\s*([\s\S]*?)```/) ?? [null, json];
+            const raw = JSON.parse(match[1] ?? json);
+            return {
+                id: raw.id ?? "orchestrated",
+                goal: raw.goal ?? fallbackGoal,
+                acceptance: (raw.acceptance ?? []).map((c) => ({
+                    id: String(c.id ?? "criterion"),
+                    text: String(c.text ?? ""),
+                    required: c.required !== false,
+                    weight: Number(c.weight ?? 1.0),
+                    machineCheckable: Boolean(c.machineCheckable ?? false),
+                })),
+                antiPatterns: (raw.antiPatterns ?? []).map(String),
+                evidenceRequired: (raw.evidenceRequired ?? []).map(String),
+            };
+        }
+        catch {
+            // Orchestrator produced unparseable output — return a minimal contract
+            return {
+                id: "fallback",
+                goal: fallbackGoal,
+                acceptance: [{ id: "complete", text: "Goal is satisfactorily completed", required: true, weight: 1.0, machineCheckable: false }],
+                antiPatterns: [],
+                evidenceRequired: [],
+            };
+        }
+    }
+}

package/dist/collaboration/pool.d.ts

@@ -0,0 +1,46 @@
+import type { Agent } from "../agent.js";
+import type { VerificationContract } from "./contract.js";
+/**
+ * Roles in a multi-agent collaboration.
+ *
+ * - orchestrator: strong-reasoning, produces VerificationContracts; no tools beyond planning
+ * - executor:     code/task execution, full tool access, sees goal + contract only
+ * - verifier:     adversarial auditor, no tools, low temperature, sees artifact + contract only
+ */
+export type AgentRole = "orchestrator" | "executor" | "verifier";
+/** Context passed to a verifier run — intentionally minimal. */
+export interface IsolatedVerifierContext {
+    contract: VerificationContract;
+    /** The artifact produced by the executor. */
+    artifact: string;
+}
+/**
+ * AgentPool manages a set of role-specific Agent instances.
+ *
+ * Each role runs in its own Agent instance with an independent history partition,
+ * ensuring that the verifier never sees the executor's implementation transcript.
+ *
+ * Usage:
+ * ```ts
+ * const pool = new AgentPool()
+ *   .add("executor", executorAgent)
+ *   .add("verifier", verifierAgent)
+ * ```
+ */
+export declare class AgentPool {
+    private agents;
+    add(role: AgentRole, agent: Agent): this;
+    has(role: AgentRole): boolean;
+    get(role: AgentRole): Agent;
+    /**
+     * Run the verifier with an isolated context — only the artifact and contract.
+     * The verifier does NOT receive the executor's conversation history.
+     * Returns a structured audit response as a plain string.
+     */
+    runVerifier(ctx: IsolatedVerifierContext): Promise<string>;
+    /**
+     * Run the orchestrator to decompose a high-level goal into a VerificationContract.
+     * The orchestrator receives the goal and must produce a structured contract in JSON.
+     */
+    runOrchestrator(goal: string): Promise<string>;
+}

package/dist/collaboration/pool.js

@@ -0,0 +1,80 @@
+import { formatContractForSystemPrompt } from "./contract.js";
+/**
+ * AgentPool manages a set of role-specific Agent instances.
+ *
+ * Each role runs in its own Agent instance with an independent history partition,
+ * ensuring that the verifier never sees the executor's implementation transcript.
+ *
+ * Usage:
+ * ```ts
+ * const pool = new AgentPool()
+ *   .add("executor", executorAgent)
+ *   .add("verifier", verifierAgent)
+ * ```
+ */
+export class AgentPool {
+    agents = new Map();
+    add(role, agent) {
+        this.agents.set(role, agent);
+        return this;
+    }
+    has(role) {
+        return this.agents.has(role);
+    }
+    get(role) {
+        const agent = this.agents.get(role);
+        if (!agent)
+            throw new Error(`AgentPool: no agent registered for role "${role}"`);
+        return agent;
+    }
+    /**
+     * Run the verifier with an isolated context — only the artifact and contract.
+     * The verifier does NOT receive the executor's conversation history.
+     * Returns a structured audit response as a plain string.
+     */
+    async runVerifier(ctx) {
+        const agent = this.get("verifier");
+        const contractBlock = formatContractForSystemPrompt(ctx.contract);
+        const auditGoal = [
+            contractBlock,
+            "",
+            "---",
+            "",
+            "## Artifact to Audit",
+            "",
+            ctx.artifact,
+            "",
+            "---",
+            "",
+            "Audit the artifact against every criterion in the contract above.",
+            "For each criterion, state whether it PASSED or FAILED and cite specific evidence.",
+            "List any anti-patterns you detected.",
+            "Conclude with an overall PASS or FAIL verdict.",
+        ].join("\n");
+        return agent.run(auditGoal);
+    }
+    /**
+     * Run the orchestrator to decompose a high-level goal into a VerificationContract.
+     * The orchestrator receives the goal and must produce a structured contract in JSON.
+     */
+    async runOrchestrator(goal) {
+        const agent = this.get("orchestrator");
+        const orchestratorGoal = [
+            `You are a planning orchestrator. Decompose the following goal into a VerificationContract.`,
+            ``,
+            `Goal: ${goal}`,
+            ``,
+            `Produce a JSON object with this schema:`,
+            `{`,
+            `  "id": "<kebab-case-id>",`,
+            `  "goal": "<restated goal>",`,
+            `  "acceptance": [{ "id": "<id>", "text": "<criterion>", "required": true, "weight": 0.x, "machineCheckable": false }],`,
+            `  "antiPatterns": ["<pattern>"],`,
+            `  "evidenceRequired": ["<evidence item>"]`,
+            `}`,
+            ``,
+            `Output ONLY the JSON object, no prose.`,
+        ].join("\n");
+        return agent.run(orchestratorGoal);
+    }
+}

package/dist/index.d.ts

@@ -32,3 +32,13 @@ export type { PermissionDecision, Permission } from "./safety/permissions.js";
 export { Governance } from "./governance.js";
 export type { GovernanceVerdict } from "./governance.js";
 export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolResultEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, LLMProvider, RetryConfig, TokenUsage, ProviderToolSpec, ProviderRunState, } from "./types.js";
+export type { AcceptanceCriterion, VerificationContract, ContractCheckResult, } from "./collaboration/contract.js";
+export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings, } from "./collaboration/contract.js";
+export { AgentPool } from "./collaboration/pool.js";
+export type { AgentRole, IsolatedVerifierContext } from "./collaboration/pool.js";
+export { ContractDrivenHarness } from "./collaboration/harness.js";
+export type { ContractOutcome, ContractHarnessOptions, Violation } from "./collaboration/harness.js";
+export { HandoffBus } from "./collaboration/handoff.js";
+export type { HandoffArtifact, ContractOutcomeInput } from "./collaboration/handoff.js";
+export { CreatorVerifierMode, OrchestrationMode } from "./collaboration/modes/creator-verifier.js";
+export type { CreatorVerifierMetrics } from "./collaboration/modes/creator-verifier.js";

package/dist/index.js

@@ -20,3 +20,8 @@ export { ScheduledPrompt } from "./signals/scheduled.js";
 export { SignalGateway } from "./signals/gateway.js";
 export { PermissionManager, PermissionMode } from "./safety/permissions.js";
 export { Governance } from "./governance.js";
+export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings, } from "./collaboration/contract.js";
+export { AgentPool } from "./collaboration/pool.js";
+export { ContractDrivenHarness } from "./collaboration/harness.js";
+export { HandoffBus } from "./collaboration/handoff.js";
+export { CreatorVerifierMode, OrchestrationMode } from "./collaboration/modes/creator-verifier.js";

package/dist/skills/loader.js

@@ -28,10 +28,10 @@ export async function scanSkillDir(skillDir) {
     const results = [];
     for (const file of files.filter(f => f.endsWith(".md"))) {
         const name = file.slice(0, -3);
-        const content = await readSkillFile(skillDir, name);
-        if (!content)
+        const raw = await readFile(path.join(skillDir, `${name}.md`), "utf8").catch(() => null);
+        if (!raw)
             continue;
-        const { meta } = parseFrontmatter(content);
+        const { meta } = parseFrontmatter(raw);
         results.push({
             name: meta.name ? String(meta.name) : name,
             description: meta.description ? String(meta.description) : "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
-    "@deepstrike/core": "0.1.9",
+    "@deepstrike/core": "0.1.11",
     "@google/generative-ai": "^0.24.1",
     "openai": "^4.77.0"
   },