@deepstrike/sdk 0.1.15 → 0.2.0

package/dist/runtime/session-log.d.ts

@@ -1,4 +1,23 @@
-import type { ProviderReplay, ToolCall } from "../types.js";
+import type { ProviderReplay, ToolCall, ToolErrorKind } from "../types.js";
+export type RollbackReason = {
+    kind: "fatal_tool_error";
+    tool_name: string;
+    error: string;
+} | {
+    kind: "governance_denied";
+    tool_name: string;
+    reason: string;
+} | {
+    kind: "provider_failure";
+    error: string;
+} | {
+    kind: "timeout";
+} | {
+    kind: "user_interrupt";
+} | {
+    kind: "malformed_replay";
+    reason: string;
+};
 export type SessionEvent = {
     kind: "run_started";
     run_id: string;
@@ -24,12 +43,85 @@ export type SessionEvent = {
         call_id: string;
         output: string;
         is_error?: boolean;
+        is_fatal?: boolean;
+        error_kind?: ToolErrorKind;
         token_count?: number;
     }>;
+} | {
+    kind: "tool_argument_repaired";
+    turn: number;
+    tool: string;
+    original_arguments: string;
+    repaired_arguments: string;
+} | {
+    kind: "tool_denied";
+    turn: number;
+    call_id: string;
+    tool_name: string;
+    reason: string;
+} | {
+    kind: "permission_requested";
+    turn: number;
+    tool: string;
+    arguments: string;
+    reason?: string;
+} | {
+    kind: "permission_resolved";
+    turn: number;
+    approved: boolean;
+    responder: string;
 } | {
     kind: "compressed";
     turn: number;
     archived_seq_range: [number, number];
+    action?: "snip_compact" | "micro_compact" | "context_collapse" | "auto_compact";
+    summary?: string;
+    summary_tokens?: number;
+    archive_ref?: string;
+    preserved_refs?: string[];
+} | {
+    kind: "rollbacked";
+    turn: number;
+    checkpoint_history_len: number;
+    reason?: RollbackReason;
+} | {
+    kind: "capability_changed";
+    turn: number;
+    added: string[];
+    removed: string[];
+    change_kind?: string;
+    capability_id?: string;
+    version?: string;
+    mounted_by?: string;
+    mount_reason?: string;
+} | {
+    kind: "milestone_advanced";
+    turn: number;
+    phase_id: string;
+    capabilities_unlocked: string[];
+} | {
+    kind: "milestone_blocked";
+    turn: number;
+    phase_id: string;
+    reason: string;
+} | {
+    kind: "milestone_evidence";
+    turn: number;
+    phase_id: string;
+    evidence: string[];
+} | {
+    kind: "checkpoint_taken";
+    turn: number;
+    history_len: number;
+} | {
+    kind: "agent_spawned";
+    turn: number;
+    agent_id: string;
+    parent_session_id: string;
+    role: string;
+    isolation: string;
+    context_inheritance: string;
+    permitted_capability_ids: string[];
 } | {
     kind: "run_terminal";
     reason: string;

package/dist/runtime/session-repair.d.ts

@@ -0,0 +1,37 @@
+import type { ProviderReplay, ToolCall } from "../types.js";
+import type { SessionEvent } from "./session-log.js";
+export { REPLAY_CONTENT_MAX_BYTES as RECOVERY_CONTENT_MAX_BYTES } from "./replay-sanitize.js";
+/** Minimal native blocks when provider_replay was not persisted. */
+export declare function synthesizeProviderReplay(content: string, toolCalls: ToolCall[]): ProviderReplay | undefined;
+export declare function effectiveProviderReplay(content: string, toolCalls: ToolCall[], stored?: ProviderReplay): ProviderReplay | undefined;
+export declare function normalizeLlmCompleted(event: Extract<SessionEvent, {
+    kind: "llm_completed";
+}>, maxBytes?: number): Extract<SessionEvent, {
+    kind: "llm_completed";
+}>;
+/** Repair event log for recovery minimum set before preload/wake. */
+export declare function repairEventsForRecovery(events: Array<{
+    seq: number;
+    event: SessionEvent;
+}>, maxBytes?: number): Array<{
+    seq: number;
+    event: SessionEvent;
+}>;
+/** Build a complete llm_completed payload for SessionLog append. */
+export declare function buildLlmCompletedEvent(input: {
+    turn: number;
+    content: string;
+    tokenCount?: number;
+    toolCalls: ToolCall[];
+    providerReplay?: ProviderReplay;
+}): Extract<SessionEvent, {
+    kind: "llm_completed";
+}>;
+/** Build run_terminal with required recovery fields. */
+export declare function buildRunTerminalEvent(input: {
+    reason: string;
+    turnsUsed: number;
+    totalTokens: number;
+}): Extract<SessionEvent, {
+    kind: "run_terminal";
+}>;

package/dist/runtime/session-repair.js

@@ -0,0 +1,77 @@
+import { sanitizeReplayText } from "./replay-sanitize.js";
+export { REPLAY_CONTENT_MAX_BYTES as RECOVERY_CONTENT_MAX_BYTES } from "./replay-sanitize.js";
+function estimateTokenCount(text) {
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+function parseToolInput(args) {
+    try {
+        return JSON.parse(args || "{}");
+    }
+    catch {
+        return {};
+    }
+}
+/** Minimal native blocks when provider_replay was not persisted. */
+export function synthesizeProviderReplay(content, toolCalls) {
+    if (!toolCalls.length)
+        return undefined;
+    const blocks = [];
+    if (content)
+        blocks.push({ type: "text", text: content });
+    for (const tc of toolCalls) {
+        blocks.push({
+            type: "tool_use",
+            id: tc.id,
+            name: tc.name,
+            input: parseToolInput(tc.arguments),
+        });
+    }
+    return { native_blocks: blocks };
+}
+export function effectiveProviderReplay(content, toolCalls, stored) {
+    if (stored?.native_blocks?.length || stored?.reasoning_content != null) {
+        return stored;
+    }
+    return synthesizeProviderReplay(content, toolCalls);
+}
+export function normalizeLlmCompleted(event, maxBytes) {
+    const content = sanitizeReplayText(event.content ?? "", maxBytes);
+    const toolCalls = event.tool_calls ?? [];
+    const providerReplay = effectiveProviderReplay(content, toolCalls, event.provider_replay);
+    return {
+        kind: "llm_completed",
+        turn: event.turn,
+        content,
+        tool_calls: toolCalls,
+        token_count: event.token_count ?? estimateTokenCount(content),
+        ...(providerReplay ? { provider_replay: providerReplay } : {}),
+    };
+}
+/** Repair event log for recovery minimum set before preload/wake. */
+export function repairEventsForRecovery(events, maxBytes) {
+    return events.map(entry => {
+        if (entry.event.kind !== "llm_completed")
+            return entry;
+        return { ...entry, event: normalizeLlmCompleted(entry.event, maxBytes) };
+    });
+}
+/** Build a complete llm_completed payload for SessionLog append. */
+export function buildLlmCompletedEvent(input) {
+    return normalizeLlmCompleted({
+        kind: "llm_completed",
+        turn: input.turn,
+        content: sanitizeReplayText(input.content),
+        tool_calls: input.toolCalls ?? [],
+        token_count: input.tokenCount,
+        provider_replay: input.providerReplay,
+    });
+}
+/** Build run_terminal with required recovery fields. */
+export function buildRunTerminalEvent(input) {
+    return {
+        kind: "run_terminal",
+        reason: input.reason,
+        turns_used: Math.max(0, input.turnsUsed),
+        total_tokens: Math.max(0, input.totalTokens),
+    };
+}

package/dist/runtime/sub-agent-orchestrator.d.ts

@@ -0,0 +1,19 @@
+import type { StreamEvent } from "../types.js";
+import type { AgentRunSpec, AgentSpawnedObservation, SubAgentResult } from "../types/agent.js";
+import type { RuntimeOptions } from "./runner.js";
+import type { SessionLog } from "./session-log.js";
+export interface SubAgentRunContext {
+    parentOpts: RuntimeOptions;
+    parentSessionId: string;
+    spec: AgentRunSpec;
+    manifest: AgentSpawnedObservation;
+    sessionLog: SessionLog;
+}
+/** Host-side driver for kernel-isolated sub-agent runs. */
+export declare class SubAgentOrchestrator {
+    stream(ctx: SubAgentRunContext): AsyncIterable<StreamEvent>;
+    run(ctx: SubAgentRunContext): Promise<SubAgentResult>;
+}
+export declare const defaultSubAgentOrchestrator: SubAgentOrchestrator;
+/** Kernel spawn without an active parent run loop (harness / coordinator use). */
+export declare function spawnStandalone(parentOpts: RuntimeOptions, parentSessionId: string, spec: AgentRunSpec, orchestrator?: SubAgentOrchestrator): Promise<SubAgentResult>;

package/dist/runtime/sub-agent-orchestrator.js

@@ -0,0 +1,114 @@
+import { agentRunSpecToKernel } from "../types/agent.js";
+import { FilteredExecutionPlane } from "./filtered-plane.js";
+import { kernelApply } from "./kernel-step.js";
+function terminationFromStatus(status) {
+    const normalized = status.toLowerCase();
+    if (normalized === "completed" ||
+        normalized === "max_turns" ||
+        normalized === "token_budget" ||
+        normalized === "timeout" ||
+        normalized === "user_abort" ||
+        normalized === "error" ||
+        normalized === "milestone_exceeded") {
+        return normalized;
+    }
+    return status;
+}
+/** Host-side driver for kernel-isolated sub-agent runs. */
+export class SubAgentOrchestrator {
+    async *stream(ctx) {
+        const permitted = new Set(ctx.manifest.permitted_capability_ids ?? []);
+        const filteredPlane = new FilteredExecutionPlane(ctx.parentOpts.executionPlane, permitted);
+        let systemPrompt = ctx.parentOpts.systemPrompt;
+        let inheritEvents;
+        if (ctx.manifest.context_inheritance === "full") {
+            inheritEvents = await ctx.sessionLog.read(ctx.parentSessionId);
+        }
+        else if (ctx.manifest.context_inheritance === "system_only") {
+            const parentEvents = await ctx.sessionLog.read(ctx.parentSessionId);
+            const started = parentEvents.find(e => e.event.kind === "run_started");
+            if (started?.event.kind === "run_started" && started.event.system_prompt) {
+                systemPrompt = started.event.system_prompt;
+            }
+        }
+        const { RuntimeRunner } = await import("./runner.js");
+        const childRunner = new RuntimeRunner({
+            ...ctx.parentOpts,
+            executionPlane: filteredPlane,
+            agentId: ctx.spec.identity.agentId,
+            systemPrompt,
+            sessionLog: ctx.sessionLog,
+        });
+        yield* childRunner.run({
+            sessionId: ctx.spec.identity.sessionId,
+            goal: ctx.spec.goal,
+            inheritEvents,
+        });
+    }
+    async run(ctx) {
+        let done;
+        let finalText = "";
+        for await (const evt of this.stream(ctx)) {
+            if (evt.type === "text_delta")
+                finalText += evt.delta;
+            if (evt.type === "done")
+                done = evt;
+        }
+        const loopResult = {
+            termination: terminationFromStatus(done?.status ?? "error"),
+            turnsUsed: done?.iterations ?? 0,
+            totalTokensUsed: done?.totalTokens ?? 0,
+            ...(finalText ? { finalMessage: { role: "assistant", content: finalText, toolCalls: [] } } : {}),
+        };
+        return { agentId: ctx.spec.identity.agentId, result: loopResult };
+    }
+}
+export const defaultSubAgentOrchestrator = new SubAgentOrchestrator();
+/** Kernel spawn without an active parent run loop (harness / coordinator use). */
+export async function spawnStandalone(parentOpts, parentSessionId, spec, orchestrator = defaultSubAgentOrchestrator) {
+    const kernel = (await import("../kernel.js")).getKernel();
+    const runtime = new kernel.KernelRuntime({
+        maxTokens: parentOpts.maxTokens,
+        maxTurns: parentOpts.maxTurns ?? 25,
+        timeoutMs: parentOpts.timeoutMs !== undefined ? BigInt(parentOpts.timeoutMs) : undefined,
+    });
+    const pending = [];
+    kernelApply(runtime, pending, { kind: "start_run", task: { goal: "coordinator", criteria: [] } });
+    const observations = kernelApply(runtime, pending, {
+        kind: "spawn_sub_agent",
+        spec: agentRunSpecToKernel(spec),
+        parent_session_id: parentSessionId,
+    });
+    const spawned = observations.find(o => o.kind === "agent_spawned");
+    if (!spawned || typeof spawned.agent_id !== "string") {
+        throw new Error("spawn_sub_agent did not emit agent_spawned");
+    }
+    const turn = spawned.turn ?? 0;
+    await parentOpts.sessionLog.append(parentSessionId, {
+        kind: "agent_spawned",
+        turn,
+        agent_id: spawned.agent_id,
+        parent_session_id: spawned.parent_session_id ?? parentSessionId,
+        role: spawned.role ?? spec.role,
+        isolation: spawned.isolation ?? spec.isolation ?? "shared",
+        context_inheritance: spawned.context_inheritance ?? "none",
+        permitted_capability_ids: spawned.permitted_capability_ids ?? [],
+    });
+    const manifest = {
+        kind: "agent_spawned",
+        turn,
+        agent_id: spawned.agent_id,
+        parent_session_id: spawned.parent_session_id ?? parentSessionId,
+        role: spawned.role ?? spec.role,
+        isolation: spawned.isolation ?? spec.isolation ?? "shared",
+        context_inheritance: spawned.context_inheritance ?? "none",
+        permitted_capability_ids: spawned.permitted_capability_ids ?? [],
+    };
+    return orchestrator.run({
+        parentOpts,
+        parentSessionId,
+        spec,
+        manifest,
+        sessionLog: parentOpts.sessionLog,
+    });
+}

package/dist/skills/watcher.d.ts

@@ -0,0 +1,19 @@
+import { type FSWatcher } from "fs";
+export type SkillChangeHandler = (skillDir: string) => void | Promise<void>;
+/**
+ * Watch a skill directory for changes and invoke `onChanged` whenever a skill
+ * file (`.md`, `.json`, or `.py`) is created, modified, or removed.
+ *
+ * Uses Node.js native `fs.watch` — no extra dependencies.
+ * The returned handle should be closed when the runner terminates.
+ *
+ * ```ts
+ * const watcher = watchSkillDir(opts.skillDir, async (dir) => {
+ *   const metas = await scanSkillDir(dir)
+ *   runtime.updateAvailableSkills(metas)
+ * })
+ * // later:
+ * watcher.close()
+ * ```
+ */
+export declare function watchSkillDir(skillDir: string, onChanged: SkillChangeHandler): FSWatcher;

package/dist/skills/watcher.js

@@ -0,0 +1,38 @@
+import { watch } from "fs";
+import { resolve, extname } from "path";
+const WATCHED_EXTS = new Set([".md", ".json", ".py"]);
+/**
+ * Watch a skill directory for changes and invoke `onChanged` whenever a skill
+ * file (`.md`, `.json`, or `.py`) is created, modified, or removed.
+ *
+ * Uses Node.js native `fs.watch` — no extra dependencies.
+ * The returned handle should be closed when the runner terminates.
+ *
+ * ```ts
+ * const watcher = watchSkillDir(opts.skillDir, async (dir) => {
+ *   const metas = await scanSkillDir(dir)
+ *   runtime.updateAvailableSkills(metas)
+ * })
+ * // later:
+ * watcher.close()
+ * ```
+ */
+export function watchSkillDir(skillDir, onChanged) {
+    const dir = resolve(skillDir);
+    let debounceTimer = null;
+    const watcher = watch(dir, { persistent: false }, (_eventType, filename) => {
+        if (!filename)
+            return;
+        if (!WATCHED_EXTS.has(extname(filename)))
+            return;
+        // Debounce: collapse rapid bursts (e.g. editor save-then-format) into one
+        // reload tick with a 200 ms window.
+        if (debounceTimer !== null)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            Promise.resolve(onChanged(dir)).catch(() => { });
+        }, 200);
+    });
+    return watcher;
+}

package/dist/tools/index.d.ts

@@ -8,7 +8,10 @@ export declare function streamingTool(name: string, description: string, paramet
 export declare function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T>;
 export declare function normalizeToolChunk(chunk: ToolChunk): Exclude<ToolChunk, string>;
 export declare function toolChunkText(chunk: ToolChunk): string;
-export declare function validateToolArguments(schemaJson: string, args: Record<string, unknown>): string | undefined;
+export declare function validateToolArguments(schemaJson: string, args: Record<string, unknown>): {
+    error?: string;
+    repaired: boolean;
+};
 export declare function executeTools(calls: {
     id: string;
     name: string;

package/dist/tools/index.js

@@ -26,25 +26,87 @@ export function validateToolArguments(schemaJson, args) {
         schema = JSON.parse(schemaJson);
     }
     catch {
-        return "invalid tool schema";
+        return { error: "invalid tool schema", repaired: false };
     }
-    return validateValue(schema, args, "$", true);
+    const state = { repaired: false };
+    const wrapper = { root: args };
+    const error = validateValue(schema, wrapper, "root", "$", state);
+    return { error, repaired: state.repaired };
 }
-function validateValue(schema, value, path, isRoot = false) {
+function validateValue(schema, parent, key, path, state) {
+    let value = parent[key];
     const expectedType = schema.type;
+    // 1. 类型自动规整 (Auto-cast)
+    if (typeof expectedType === "string") {
+        if (expectedType === "boolean") {
+            if (value === "true") {
+                parent[key] = true;
+                value = true;
+                state.repaired = true;
+            }
+            else if (value === "false") {
+                parent[key] = false;
+                value = false;
+                state.repaired = true;
+            }
+        }
+        else if (expectedType === "number" || expectedType === "integer") {
+            if (typeof value === "string") {
+                const num = Number(value);
+                if (!Number.isNaN(num)) {
+                    if (expectedType === "integer") {
+                        if (Number.isInteger(num)) {
+                            parent[key] = num;
+                            value = num;
+                            state.repaired = true;
+                        }
+                    }
+                    else {
+                        parent[key] = num;
+                        value = num;
+                        state.repaired = true;
+                    }
+                }
+            }
+        }
+    }
+    // 2. 补默认值 (Default Injection)
+    if (expectedType === "object") {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return `${path} must be object`;
+        }
+        const properties = schema.properties ?? {};
+        for (const [propKey, childSchema] of Object.entries(properties)) {
+            if (!(propKey in value)) {
+                if ("default" in childSchema) {
+                    value[propKey] = childSchema.default;
+                    state.repaired = true;
+                }
+            }
+        }
+    }
+    // 3. 校验并递归
     if (typeof expectedType === "string") {
         if (expectedType === "object") {
             if (!value || typeof value !== "object" || Array.isArray(value))
                 return `${path} must be object`;
             const obj = value;
+            // 3a. 裁剪多余字段
+            const properties = schema.properties ?? {};
+            const allowedKeys = new Set(Object.keys(properties));
+            for (const objKey of Object.keys(obj)) {
+                if (!allowedKeys.has(objKey)) {
+                    delete obj[objKey];
+                    state.repaired = true;
+                }
+            }
             for (const required of schema.required ?? []) {
                 if (!(required in obj))
                     return `${path}.${required} is required`;
             }
-            const properties = schema.properties ?? {};
-            for (const [key, child] of Object.entries(properties)) {
-                if (key in obj) {
-                    const err = validateValue(child, obj[key], `${path}.${key}`);
+            for (const [propKey, child] of Object.entries(properties)) {
+                if (propKey in obj) {
+                    const err = validateValue(child, obj, propKey, `${path}.${propKey}`, state);
                     if (err)
                         return err;
                 }
@@ -53,6 +115,15 @@ function validateValue(schema, value, path, isRoot = false) {
         else if (expectedType === "array") {
             if (!Array.isArray(value))
                 return `${path} must be array`;
+            const arr = value;
+            const itemsSchema = schema.items;
+            if (itemsSchema) {
+                for (let i = 0; i < arr.length; i++) {
+                    const err = validateValue(itemsSchema, arr, i, `${path}[${i}]`, state);
+                    if (err)
+                        return err;
+                }
+            }
         }
         else if (expectedType === "string") {
             if (typeof value !== "string")
@@ -71,7 +142,7 @@ function validateValue(schema, value, path, isRoot = false) {
                 return `${path} must be boolean`;
         }
     }
-    else if (isRoot && (!value || typeof value !== "object" || Array.isArray(value))) {
+    else if (path === "$" && (!value || typeof value !== "object" || Array.isArray(value))) {
         return `${path} must be object`;
     }
     if (Array.isArray(schema.enum) && !schema.enum.includes(value))
@@ -85,9 +156,9 @@ export async function executeTools(calls, registry) {
             return { callId: c.id, output: `unknown tool: ${c.name}`, isError: true };
         try {
             const args = JSON.parse(c.arguments || "{}");
-            const validationError = validateToolArguments(t.schema.parameters, args);
-            if (validationError)
-                return { callId: c.id, output: `invalid arguments: ${validationError}`, isError: true };
+            const validation = validateToolArguments(t.schema.parameters, args);
+            if (validation.error)
+                return { callId: c.id, output: `invalid arguments: ${validation.error}`, isError: true };
             const output = await t.execute(args);
             if (isAsyncIterable(output)) {
                 let combined = "";

package/dist/types/agent.d.ts

@@ -0,0 +1,68 @@
+import type { Message } from "../types.js";
+export type KernelAgentRole = "explore" | "plan" | "implement" | "verify" | "custom";
+export type AgentIsolation = "shared" | "read_only" | "worktree" | "remote";
+export type ContextInheritance = "none" | "system_only" | "full";
+export type TerminationReason = "completed" | "max_turns" | "token_budget" | "timeout" | "user_abort" | "error" | "milestone_exceeded";
+export type MilestonePolicy = "require_verifier" | "terminate" | "auto_pass";
+export interface AgentIdentity {
+    agentId: string;
+    sessionId: string;
+    isSubAgent: boolean;
+    parentSessionId?: string;
+}
+export interface AgentCapabilityFilter {
+    allowedKinds?: string[];
+    allowedIds?: string[];
+}
+export interface AgentRunSpec {
+    identity: AgentIdentity;
+    role: KernelAgentRole;
+    isolation?: AgentIsolation;
+    goal: string;
+    verificationContractId?: string;
+    capabilityFilter?: AgentCapabilityFilter;
+    milestones?: MilestoneContract;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentSpawnedObservation {
+    kind: "agent_spawned";
+    turn?: number;
+    agent_id: string;
+    parent_session_id: string;
+    role: string;
+    isolation: string;
+    context_inheritance: string;
+    permitted_capability_ids: string[];
+}
+export interface LoopResult {
+    termination: TerminationReason | string;
+    finalMessage?: Message;
+    turnsUsed: number;
+    totalTokensUsed: number;
+}
+export interface SubAgentResult {
+    agentId: string;
+    result: LoopResult;
+}
+export interface MilestoneCheckResult {
+    phaseId: string;
+    passed: boolean;
+    reason?: string;
+}
+export interface MilestonePhase {
+    id: string;
+    criteria?: string[];
+    unlocks?: Array<Record<string, unknown>>;
+    verifier?: Record<string, unknown>;
+    requiredEvidence?: string[];
+}
+export interface MilestoneContract {
+    phases: MilestonePhase[];
+}
+export declare function agentIdentitySub(agentId: string, sessionId: string, parentSessionId?: string): AgentIdentity;
+export declare function agentRunSpecToKernel(spec: AgentRunSpec): Record<string, unknown>;
+export declare function milestoneContractToKernel(contract: MilestoneContract): Record<string, unknown>;
+export declare function milestoneCheckResultToKernel(result: MilestoneCheckResult): Record<string, unknown>;
+export declare function subAgentResultToKernel(result: SubAgentResult): Record<string, unknown>;
+export declare function milestoneCheckPass(phaseId: string): MilestoneCheckResult;
+export declare function milestoneCheckFail(phaseId: string, reason: string): MilestoneCheckResult;