@deepstrike/sdk 0.2.5 → 0.2.6

package/README.md

@@ -222,6 +222,23 @@ const runner = new RuntimeRunner({
   timeoutMs: 60_000,
   schedulerBudget: { maxWallMs: 300_000 },
 
+  // Resource quotas (M2) — enforced at the kernel syscall trap. Opt-in; omit for unbounded.
+  resourceQuota: {
+    maxConcurrentSubagents: 4,                       // deny spawn while at cap
+    maxSpawnDepth: 2,                                // deny spawn past nesting depth
+    memoryWritesPerWindow: { maxWrites: 20, windowMs: 60_000 }, // rate-limit writeMemory
+  },
+
+  // Long-term memory policy (set_memory_policy) — opt-in, kernel-enforced; omit for defaults.
+  memoryPolicy: {
+    memoryPath: "./.memory",     // where the SDK persists/scans memories (SDK-consumed)
+    staleWarningDays: 30,        // flag recalled memories older than this (SDK-consumed)
+    retrievalTopK: 5,            // kernel caps query_memory requested_k to this
+    validationEnabled: true,     // false → admit writes without validation
+    maxContentBytes: 10_000,     // override write_memory content-size limit
+    maxNameLength: 100,          // override write_memory name-length limit
+  },
+
   // Agent OS native profile (defaults shown)
   governancePolicy: DEFAULT_NATIVE_GOVERNANCE_POLICY,
   attentionPolicy: DEFAULT_NATIVE_ATTENTION_POLICY, // SignalRouter queue size 64
@@ -260,6 +277,8 @@ const runner = new RuntimeRunner({
 |--------|---------|
 | `governancePolicy` | Declarative deny / ask_user / rate-limit / param rules loaded into the kernel before `start_run` |
 | `attentionPolicy` | In-kernel signal router queue size (default 64) |
+| `resourceQuota` | M2 declarative limits — `maxConcurrentSubagents` / `maxSpawnDepth` / `memoryWritesPerWindow` — enforced at the kernel syscall trap (`set_resource_quota`); over-quota spawns roll back, over-rate writes surface as `memory_validation_failed` |
+| `memoryPolicy` | Long-term memory config sent as `set_memory_policy` and **kernel-enforced**: `validationEnabled: false` admits writes without validation, `maxContentBytes` / `maxNameLength` override validation limits, `retrievalTopK` caps `query_memory` breadth; `memoryPath` / `staleWarningDays` are SDK-consumed (requires `dreamStore` + `agentId` to enable memory) |
 | `onPermissionRequest` | Resolves `tool_gated` + `suspended` → kernel `resume` with approved/denied call IDs |
 | `compressionStore` | Writes archived messages on `compressed` observations |
 | `asyncSummarizer` | Background LLM summary after compression; stored as `summary_upgraded` |

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
-export type { RuntimeOptions } from "./runtime/runner.js";
+export type { RuntimeOptions, SchedulerBudget } from "./runtime/runner.js";
+export type { MemoryPolicy, MemoryWriteRateLimit, ResourceQuota } from "./kernel.js";
 export { KernelPrimitivesDashboard } from "./runtime/kernel-primitives-dashboard.js";
 export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
@@ -8,7 +9,8 @@ export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export type { ExecutionPlane, RunContext } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
 export type { SessionLog, SessionEvent } from "./runtime/session-log.js";
-export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, } from "./runtime/os-profile.js";
+export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "./runtime/os-profile.js";
+export type { NativeOsProfile, OsProfileId } from "./runtime/os-profile.js";
 export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories, } from "./runtime/os-snapshot.js";
 export type { OsSnapshot } from "./runtime/os-snapshot.js";
 export { categoryForKind, kernelObservationToSessionEvent } from "./runtime/kernel-event-log.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
 export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
-export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, } from "./runtime/os-profile.js";
+export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "./runtime/os-profile.js";
 export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories, } from "./runtime/os-snapshot.js";
 export { categoryForKind, kernelObservationToSessionEvent } from "./runtime/kernel-event-log.js";
 export { NullArchiveStore, FileArchiveStore } from "./runtime/archive.js";

package/dist/kernel.d.ts

@@ -4,6 +4,49 @@ export interface GovernanceVerdict {
     reason?: string;
     retryAfterMs?: number;
 }
+/**
+ * M2 资源配额 — declarative resource limits enforced at the kernel's single syscall trap.
+ *
+ * Installed through the versioned JSON event ABI (`set_resource_quota`), not a side-channel
+ * setter, so quota config is replayable and session-loggable like governance/scheduler config.
+ * Every field is optional; an omitted field imposes no limit, and omitting the quota entirely
+ * preserves the pre-M2 behavior of admitting all spawn / memory-write syscalls.
+ */
+export interface MemoryWriteRateLimit {
+    maxWrites: number;
+    windowMs: number;
+}
+export interface ResourceQuota {
+    /** Max sub-agents in the `running` state at once; further spawns are denied while at cap. */
+    maxConcurrentSubagents?: number;
+    /** Max sub-agent nesting depth (direct children of the root loop are depth 1). */
+    maxSpawnDepth?: number;
+    /** Rolling-window memory-write rate limit: at most `maxWrites` per any `windowMs` span. */
+    memoryWritesPerWindow?: MemoryWriteRateLimit;
+}
+/**
+ * Long-term memory policy — declarative knobs for the kernel's memory subsystem.
+ *
+ * Installed through the versioned JSON event ABI (`set_memory_policy`), the same channel as
+ * governance / scheduler / quota config, so memory configuration is replayable and
+ * session-loggable rather than a side-channel setter. Installing the policy is opt-in and
+ * kernel-enforced; omitted fields fall back to the kernel defaults (empty path, 2-day stale
+ * warning, top-5 retrieval, validation on). Enabling memory is still `dreamStore` + `agentId`.
+ */
+export interface MemoryPolicy {
+    /** Filesystem root the SDK uses to persist/scan memories; carried for SDK recall I/O. */
+    memoryPath?: string;
+    /** Age after which a recalled memory is flagged stale (days); consumed SDK-side. */
+    staleWarningDays?: number;
+    /** Upper bound on retrieval breadth: the kernel clamps `query_memory` top-k to this. */
+    retrievalTopK?: number;
+    /** When false, the kernel admits every `write_memory` without validation. */
+    validationEnabled?: boolean;
+    /** Override the kernel's `write_memory` content-size limit (bytes). */
+    maxContentBytes?: number;
+    /** Override the kernel's `write_memory` name-length limit. */
+    maxNameLength?: number;
+}
 export interface GovernanceInstance {
     setIdentity(agentId: string, sessionId: string): void;
     addPermissionRule(pattern: string, action: "allow" | "deny" | "ask_user"): void;

package/dist/memory/agent.d.ts

@@ -10,53 +10,8 @@
  * - SDK performs I/O and selection
  * - LLM (Sonnet) acts as selector, not vector similarity
  */
-import type { SessionData, MemoryEntry } from "./protocols.js";
-/**
- * Memory metadata (matches kernel MemoryMetadata structure).
- */
-export interface MemoryMetadata {
-    name: string;
-    description: string;
-    kind?: MemoryKind;
-    created_at: number;
-    updated_at: number;
-    session_id?: string;
-    user_role?: string;
-    expertise_level?: string;
-    preference_rule?: string;
-    approved_pattern?: string;
-    project_phase?: string;
-    relative_date?: string;
-    external_url?: string;
-    ticket_ref?: string;
-}
-/**
- * Memory kind (4 types, mirroring Claude Code).
- */
-export type MemoryKind = "user" | "feedback" | "project" | "reference";
-/**
- * Memory write request (SDK → kernel).
- */
-export interface MemoryWriteRequest {
-    metadata: MemoryMetadata;
-    content: string;
-}
-/**
- * Memory query request (kernel → SDK).
- */
-export interface MemoryQuery {
-    current_context: string;
-    active_tools: string[];
-    already_surfaced: string[];
-    top_k: number;
-}
-/**
- * Memory retrieval response (SDK → kernel).
- */
-export interface MemoryRetrieval {
-    selected_memory_ids: string[];
-    selection_rationale: string;
-}
+import type { SessionData, MemoryEntry, MemoryKind, MemoryMetadata, MemoryWriteRequest, MemoryQuery, MemoryRetrieval } from "./protocols.js";
+export type { MemoryKind, MemoryMetadata, MemoryWriteRequest, MemoryQuery, MemoryRetrieval, } from "./protocols.js";
 /**
  * Memory index entry (from MEMORY.md).
  */

package/dist/runtime/os-profile.d.ts

@@ -1,4 +1,12 @@
 import type { GovernancePolicy } from "../governance.js";
+export type OsProfileId = "native";
+export interface NativeOsProfile {
+    id: OsProfileId;
+    attentionPolicy: {
+        maxQueueSize?: number;
+    };
+    governancePolicy: GovernancePolicy;
+}
 /** Default attention policy for native profile smoke tests. */
 export declare const DEFAULT_NATIVE_ATTENTION_POLICY: {
     maxQueueSize: number;
@@ -7,6 +15,10 @@ export declare const DEFAULT_NATIVE_ATTENTION_POLICY: {
 export declare const DEFAULT_NATIVE_GOVERNANCE_POLICY: GovernancePolicy;
 /** Default restrictive sandbox policy template requiring confirmation for modification/execution. */
 export declare const DEFAULT_SANDBOX_POLICY: GovernancePolicy;
+/** Resolve a named OS profile into concrete kernel-owned policy defaults. */
+export declare function osProfile(profile?: OsProfileId | NativeOsProfile): NativeOsProfile;
+/** Assert that a runtime is using a valid native microkernel policy profile. */
+export declare function assertNativeProfile(profile?: OsProfileId | NativeOsProfile): NativeOsProfile;
 /**
  * Validates the declarative policies statically to prevent runtime crashes when loaded into the microkernel.
  */

package/dist/runtime/os-profile.js

@@ -13,6 +13,30 @@ export const DEFAULT_SANDBOX_POLICY = {
         { pattern: "*", action: "deny" },
     ],
 };
+/** Resolve a named OS profile into concrete kernel-owned policy defaults. */
+export function osProfile(profile = "native") {
+    if (typeof profile !== "string")
+        return profile;
+    if (profile !== "native")
+        throw new Error(`Unsupported OS profile: ${profile}`);
+    return {
+        id: "native",
+        attentionPolicy: DEFAULT_NATIVE_ATTENTION_POLICY,
+        governancePolicy: DEFAULT_NATIVE_GOVERNANCE_POLICY,
+    };
+}
+/** Assert that a runtime is using a valid native microkernel policy profile. */
+export function assertNativeProfile(profile = "native") {
+    const resolved = osProfile(profile);
+    if (resolved.id !== "native") {
+        throw new Error(`Unsupported OS profile: ${resolved.id}`);
+    }
+    const validation = validateDeclarativePolicy(resolved.governancePolicy, resolved.attentionPolicy);
+    if (!validation.valid) {
+        throw new Error(`Invalid native OS profile: ${validation.errors.join("; ")}`);
+    }
+    return resolved;
+}
 /**
  * Validates the declarative policies statically to prevent runtime crashes when loaded into the microkernel.
  */

package/dist/runtime/runner.d.ts

@@ -5,10 +5,15 @@ import type { SignalSource } from "../signals/types.js";
 import type { SessionLog, SessionEvent } from "./session-log.js";
 import type { ArchiveStore } from "./archive.js";
 import type { ExecutionPlane } from "./execution-plane.js";
+import { type MemoryPolicy, type ResourceQuota } from "../kernel.js";
 import type { AgentRunSpec, MilestoneCheckResult, MilestoneContract, MilestonePolicy } from "../types/agent.js";
 import { type SubAgentOrchestrator } from "./sub-agent-orchestrator.js";
 import { type GovernancePolicy } from "../governance.js";
+import { type NativeOsProfile, type OsProfileId } from "./os-profile.js";
 import { LargeResultSpool } from "./large-result-spool.js";
+export interface SchedulerBudget {
+    maxWallMs?: number;
+}
 export interface RuntimeOptions {
     provider: LLMProvider;
     sessionLog: SessionLog;
@@ -24,6 +29,8 @@ export interface RuntimeOptions {
     knowledgeSource?: KnowledgeSource;
     signalSource?: SignalSource;
     extensions?: Record<string, unknown>;
+    /** Named or concrete OS profile. Defaults to the native microkernel profile. */
+    osProfile?: OsProfileId | NativeOsProfile;
     /**
      * Declarative governance policy loaded into the kernel (`load_governance_policy`).
      * The kernel enforces deny/veto/rate-limit/param-constraint before tools execute;
@@ -44,9 +51,19 @@ export interface RuntimeOptions {
      * in milliseconds; when set, the kernel terminates the run when exceeded.
      * Other axes (maxTurns, maxTokens) are set via RuntimeOptions directly.
      */
-    schedulerBudget?: {
-        maxWallMs?: number;
-    };
+    schedulerBudget?: SchedulerBudget;
+    /**
+     * Optional declarative resource quotas (`set_resource_quota`). Bounds spawn concurrency /
+     * nesting depth and memory-write rate at the kernel's single syscall trap. When unset, spawn
+     * and memory-write syscalls are admitted unconditionally (pre-M2 behavior).
+     */
+    resourceQuota?: ResourceQuota;
+    /**
+     * Optional long-term memory policy (`set_memory_policy`). Tunes the kernel's memory subsystem
+     * (retrieval top-k, stale-warning age, write validation, memory path). Unset leaves the kernel
+     * defaults. Enabling memory still requires `dreamStore` + `agentId`.
+     */
+    memoryPolicy?: MemoryPolicy;
     tokenizer?: string;
     enablePlanTool?: boolean;
     /**

package/dist/runtime/runner.js

@@ -10,7 +10,7 @@ import { agentRunSpecToKernel, findSpawnProcessObservation, milestoneCheckPass,
 import { defaultSubAgentOrchestrator } from "./sub-agent-orchestrator.js";
 import { governancePolicyToKernelEvent } from "../governance.js";
 import { kernelObservationToSessionEvent, withCategory } from "./kernel-event-log.js";
-import { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY } from "./os-profile.js";
+import { assertNativeProfile } from "./os-profile.js";
 import { LargeResultSpool } from "./large-result-spool.js";
 export class RuntimeRunner {
     opts;
@@ -504,6 +504,20 @@ export class RuntimeRunner {
         if (this.opts.dreamStore && this.opts.agentId) {
             kernelApply(runtime, this.pendingObservations, { kind: "set_memory_enabled", enabled: true });
         }
+        // Install optional memory policy. Maps the ergonomic camelCase option onto the kernel's
+        // snake_case `set_memory_policy` event; omitted fields fall back to kernel defaults.
+        if (this.opts.memoryPolicy) {
+            const m = this.opts.memoryPolicy;
+            kernelApply(runtime, this.pendingObservations, {
+                kind: "set_memory_policy",
+                ...(m.memoryPath !== undefined ? { memory_path: m.memoryPath } : {}),
+                ...(m.staleWarningDays !== undefined ? { stale_warning_days: m.staleWarningDays } : {}),
+                ...(m.retrievalTopK !== undefined ? { retrieval_top_k: m.retrievalTopK } : {}),
+                ...(m.validationEnabled !== undefined ? { validation_enabled: m.validationEnabled } : {}),
+                ...(m.maxContentBytes !== undefined ? { max_content_bytes: m.maxContentBytes } : {}),
+                ...(m.maxNameLength !== undefined ? { max_name_length: m.maxNameLength } : {}),
+            });
+        }
         if (this.opts.knowledgeSource) {
             kernelApply(runtime, this.pendingObservations, { kind: "set_knowledge_enabled", enabled: true });
         }
@@ -542,8 +556,9 @@ export class RuntimeRunner {
         if (this.opts.runSpec) {
             startPayload.run_spec = agentRunSpecToKernel(this.opts.runSpec);
         }
-        const attentionPolicy = this.opts.attentionPolicy ?? DEFAULT_NATIVE_ATTENTION_POLICY;
-        const governancePolicy = this.opts.governancePolicy ?? DEFAULT_NATIVE_GOVERNANCE_POLICY;
+        const osProfile = assertNativeProfile(this.opts.osProfile ?? "native");
+        const attentionPolicy = this.opts.attentionPolicy ?? osProfile.attentionPolicy;
+        const governancePolicy = this.opts.governancePolicy ?? osProfile.governancePolicy;
         // Load the declarative governance policy into the kernel before the run starts,
         // so the in-kernel gate enforces deny/veto/rate-limit/param before any tool runs.
         kernelApply(runtime, this.pendingObservations, governancePolicyToKernelEvent(governancePolicy));
@@ -563,6 +578,29 @@ export class RuntimeRunner {
                     : {}),
             });
         }
+        // Install optional resource quotas at the syscall trap (M2). Maps the ergonomic camelCase
+        // option onto the kernel's snake_case quota shape; the write-rate window is the serde tuple
+        // `[maxWrites, windowMs]`. Omitting the option leaves spawn / memory writes unbounded.
+        if (this.opts.resourceQuota) {
+            const q = this.opts.resourceQuota;
+            kernelApply(runtime, this.pendingObservations, {
+                kind: "set_resource_quota",
+                quota: {
+                    ...(q.maxConcurrentSubagents !== undefined
+                        ? { max_concurrent_subagents: q.maxConcurrentSubagents }
+                        : {}),
+                    ...(q.maxSpawnDepth !== undefined ? { max_spawn_depth: q.maxSpawnDepth } : {}),
+                    ...(q.memoryWritesPerWindow !== undefined
+                        ? {
+                            memory_writes_per_window: [
+                                q.memoryWritesPerWindow.maxWrites,
+                                q.memoryWritesPerWindow.windowMs,
+                            ],
+                        }
+                        : {}),
+                },
+            });
+        }
         let action = resumeMidRun
             ? kernelAction(runtime, this.pendingObservations, { kind: "resume" })
             : kernelAction(runtime, this.pendingObservations, startPayload);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.5",
+    "@deepstrike/core": "0.2.6",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },