@nebutra/agent-runtime 0.2.0 → 0.2.1

package/dist/loop.d.ts

@@ -2,7 +2,7 @@ import { TurnConfig, TurnUsage, ThreadEvent } from './model.js';
 import { ReviewDecision, RuleDecision, ApprovalPolicy } from './policy.js';
 import { ServerRequest } from './protocol.js';
 import { RolloutStore } from './rollout.js';
-import { ToolRegistry } from './tools.js';
+import { RuntimeToolRegistry } from './tools.js';
 import 'zod';
 
 /**
@@ -60,7 +60,7 @@ interface RunTurnDeps {
     readonly config: TurnConfig;
     readonly approvalPolicy: ApprovalPolicy;
     readonly model: ModelInvoker;
-    readonly tools: ToolRegistry;
+    readonly tools: RuntimeToolRegistry;
     readonly store: RolloutStore;
     readonly approvalGate: ApprovalGate;
     /** Defaults to: everything requires a prompt (safe). */

package/dist/loop.js

@@ -1,8 +1,9 @@
 import {
   runTurn
-} from "./chunk-BJBBR3QA.js";
-import "./chunk-CGRCUKGT.js";
+} from "./chunk-D4YAPLOW.js";
 import "./chunk-37BBB2P2.js";
+import "./chunk-CGRCUKGT.js";
+import "./chunk-424PT5DM.js";
 export {
   runTurn
 };

package/dist/mcp-bridge.d.ts

@@ -1,4 +1,4 @@
-import { ToolDefinition, ToolRegistry, McpClientLike } from './tools.js';
+import { ToolDefinition, RuntimeToolRegistry, McpClientLike } from './tools.js';
 import 'zod';
 
 /**
@@ -36,11 +36,11 @@ interface ActivateMcpToolsResult {
 }
 /**
  * List the tenant/plan-visible MCP tools, adapt each via {@link adaptMcpTool},
- * and register them into the {@link ToolRegistry}. A tool whose name is already
+ * and register them into the {@link RuntimeToolRegistry}. A tool whose name is already
  * registered is skipped (reported, never thrown). Empty/blank tenantId fails
  * closed before any catalog call.
  */
-declare function activateMcpTools(registry: ToolRegistry, catalog: McpServerCatalogPort, client: McpClientLike, ctx: {
+declare function activateMcpTools(registry: RuntimeToolRegistry, catalog: McpServerCatalogPort, client: McpClientLike, ctx: {
     tenantId: string;
     plan?: string;
 }): Promise<ActivateMcpToolsResult>;

package/dist/mcp-bridge.js

@@ -1,7 +1,8 @@
 import {
   activateMcpTools
-} from "./chunk-PGGWSUTM.js";
-import "./chunk-NN7DATXA.js";
+} from "./chunk-NI4EDT4T.js";
+import "./chunk-4Y25ZTKI.js";
+import "./chunk-424PT5DM.js";
 export {
   activateMcpTools
 };

package/dist/model.js

@@ -2,6 +2,7 @@ import {
   isTurnTerminal,
   mergeTurnConfig
 } from "./chunk-6EGG2OZC.js";
+import "./chunk-424PT5DM.js";
 export {
   isTurnTerminal,
   mergeTurnConfig

package/dist/orchestration.d.ts

@@ -0,0 +1,43 @@
+import { TurnUsage } from './model.js';
+
+interface BudgetCap {
+    readonly durationMs: number;
+    readonly costUsd: number;
+    readonly tokenLimit: number;
+}
+interface Brief {
+    readonly id: string;
+    readonly objective: string;
+    readonly outputFormat: Record<string, unknown>;
+    readonly allowedTools: readonly string[];
+    readonly contextRefs: readonly string[];
+    readonly boundaries: readonly string[];
+    readonly budget: BudgetCap;
+    readonly dependsOn?: readonly string[];
+}
+type DispatchStrategy = "auto" | "sequential" | "fanout";
+interface DispatchPlan {
+    readonly strategy: Exclude<DispatchStrategy, "auto">;
+    readonly order: readonly Brief[];
+}
+interface DispatchPlanOptions {
+    readonly strategy?: DispatchStrategy;
+}
+interface SubagentResult {
+    readonly briefId: string;
+    readonly output: unknown;
+    readonly usage: TurnUsage;
+    readonly durationMs: number;
+}
+interface SubagentCostReport {
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalReasoningTokens: number;
+    readonly maxDurationMs: number;
+    readonly subagents: number;
+}
+declare function planSubagentDispatch(briefs: readonly Brief[], options?: DispatchPlanOptions): DispatchPlan;
+declare function fanOutSubagents(briefs: readonly Brief[], run: (brief: Brief) => Promise<SubagentResult>): Promise<readonly SubagentResult[]>;
+declare function costReport(results: readonly SubagentResult[]): SubagentCostReport;
+
+export { type Brief, type BudgetCap, type DispatchPlan, type DispatchPlanOptions, type DispatchStrategy, type SubagentCostReport, type SubagentResult, costReport, fanOutSubagents, planSubagentDispatch };

package/dist/orchestration.js

@@ -0,0 +1,12 @@
+import {
+  costReport,
+  fanOutSubagents,
+  planSubagentDispatch
+} from "./chunk-MX2WL43P.js";
+import "./chunk-424PT5DM.js";
+export {
+  costReport,
+  fanOutSubagents,
+  planSubagentDispatch
+};
+//# sourceMappingURL=orchestration.js.map

package/dist/orchestration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/policy.js

@@ -9,6 +9,7 @@ import {
   resolveRuleDecision,
   writableRootSchema
 } from "./chunk-CGRCUKGT.js";
+import "./chunk-424PT5DM.js";
 export {
   DEFAULT_APPROVAL_POLICY,
   DEFAULT_CAPABILITY_POLICY,

package/dist/protocol.js

@@ -5,6 +5,7 @@ import {
   resolveScope,
   scopeKey
 } from "./chunk-FUG5DT2C.js";
+import "./chunk-424PT5DM.js";
 export {
   METHOD_REGISTRY,
   NOTIFICATIONS,

package/dist/pulsar.d.ts

@@ -0,0 +1,78 @@
+import { ModelInvoker, ApprovalGate } from './loop.js';
+import { TurnConfig, ThreadEvent } from './model.js';
+import { ApprovalPolicy } from './policy.js';
+import { RolloutStore } from './rollout.js';
+import { RuntimeToolRegistry } from './tools.js';
+import './protocol.js';
+import 'zod';
+
+type EventLogKind = "llm_call" | "tool_call" | "sub_agent_call" | "content_write";
+interface PulsarEventInput {
+    readonly traceId: string;
+    readonly kind: EventLogKind;
+    readonly affected: readonly string[];
+    readonly parent: string | null;
+    readonly snapshot?: Record<string, string>;
+}
+interface PulsarBranchRecord {
+    readonly name: string;
+    readonly from: string;
+    readonly at: string;
+}
+interface PulsarEventLogPort {
+    commit(event: PulsarEventInput): Promise<string>;
+    branchFrom(id: string, name: string): Promise<PulsarBranchRecord>;
+}
+interface StartThreadOptions {
+    readonly threadId?: string;
+    readonly maxSteps?: number;
+}
+interface PulsarDeps {
+    readonly tenantId: string;
+    readonly config: TurnConfig;
+    readonly model: ModelInvoker;
+    readonly tools: RuntimeToolRegistry;
+    readonly store: RolloutStore;
+    readonly approvalGate: ApprovalGate;
+    readonly approvalPolicy: ApprovalPolicy;
+    readonly eventLog?: PulsarEventLogPort;
+}
+declare class PulsarThread {
+    #private;
+    readonly id: string;
+    readonly playId: string;
+    readonly tenantId: string;
+    constructor(input: {
+        readonly id: string;
+        readonly playId: string;
+        readonly tenantId: string;
+        readonly deps: PulsarDeps;
+        readonly mode: "start" | "resume";
+        readonly userInput: string;
+        readonly maxSteps?: number;
+    });
+    subscribe(): AsyncGenerator<ThreadEvent>;
+}
+declare class PulsarBuilder {
+    #private;
+    withTenant(tenantId: string): this;
+    withConfig(config: TurnConfig): this;
+    withModel(model: ModelInvoker): this;
+    withTools(tools: RuntimeToolRegistry): this;
+    withRolloutStore(store: RolloutStore): this;
+    withApprovalGate(approvalGate: ApprovalGate): this;
+    withApprovalPolicy(policy: ApprovalPolicy): this;
+    withEventLog(eventLog: PulsarEventLogPort): this;
+    build(): Pulsar;
+}
+declare class Pulsar {
+    #private;
+    static readonly itemCommitIds: Map<string, string>;
+    constructor(deps: PulsarDeps);
+    static builder(): PulsarBuilder;
+    startPlay(playId: string, input: string, options?: StartThreadOptions): Promise<PulsarThread>;
+    resume(threadId: string): Promise<PulsarThread>;
+    branchFromItem(threadId: string, itemId: string, name: string): Promise<PulsarBranchRecord>;
+}
+
+export { Pulsar, type PulsarBranchRecord, PulsarBuilder, type PulsarDeps, type PulsarEventInput, type PulsarEventLogPort, PulsarThread, type StartThreadOptions };

package/dist/pulsar.js

@@ -0,0 +1,17 @@
+import {
+  Pulsar,
+  PulsarBuilder,
+  PulsarThread
+} from "./chunk-KCNN4QUQ.js";
+import "./chunk-D4YAPLOW.js";
+import "./chunk-37BBB2P2.js";
+import "./chunk-4Y25ZTKI.js";
+import "./chunk-6EGG2OZC.js";
+import "./chunk-CGRCUKGT.js";
+import "./chunk-424PT5DM.js";
+export {
+  Pulsar,
+  PulsarBuilder,
+  PulsarThread
+};
+//# sourceMappingURL=pulsar.js.map

package/dist/pulsar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/rollout-store-persistent.js

@@ -2,6 +2,7 @@ import {
   PersistentRolloutStore,
   RoundTripError
 } from "./chunk-2DA6Q6TN.js";
+import "./chunk-424PT5DM.js";
 export {
   PersistentRolloutStore,
   RoundTripError

package/dist/rollout.js

@@ -5,6 +5,7 @@ import {
   replay,
   sanitizeForPersist
 } from "./chunk-37BBB2P2.js";
+import "./chunk-424PT5DM.js";
 export {
   InMemoryRolloutStore,
   PERSISTED_OUTPUT_MAX_BYTES,

package/dist/sandbox.js

@@ -5,6 +5,7 @@ import {
   assertSafePosture,
   createHttpSandbox
 } from "./chunk-MUF7ZZTO.js";
+import "./chunk-424PT5DM.js";
 export {
   NoExecutorConfiguredError,
   REFUSING_SANDBOX,

package/dist/skills.js

@@ -1,8 +1,9 @@
 import {
   buildSkillListing,
   expandSkill
-} from "./chunk-ZMYX5VBU.js";
+} from "./chunk-GQZKYWFT.js";
 import "./chunk-7BUOF367.js";
+import "./chunk-424PT5DM.js";
 export {
   buildSkillListing,
   expandSkill

package/dist/subagents.js

@@ -8,6 +8,7 @@ import {
   resolveSubagentTools,
   settleDeferred
 } from "./chunk-5YS7WAPS.js";
+import "./chunk-424PT5DM.js";
 export {
   TASK_KINDS,
   TASK_STATUSES,

package/dist/tools.d.ts

@@ -46,16 +46,17 @@ interface ToolHooks {
     readonly postToolUse?: (name: string, output: unknown, ctx: ToolDispatchContext) => Promise<void>;
 }
 /**
- * registry -> router -> orchestrator pipeline. MCP tools register via
+ * runtime registry -> router -> orchestrator pipeline. MCP tools register via
  * {@link adaptMcpTool} and are dispatched identically to native tools.
  */
-declare class ToolRegistry {
+declare class RuntimeToolRegistry {
     #private;
     constructor(hooks?: ToolHooks);
     register<I, O>(definition: ToolDefinition<I, O>, handler: ToolHandler<I, O>, origin?: ToolOrigin): void;
     list(): readonly RegisteredTool[];
     dispatch(name: string, rawInput: unknown, ctx: ToolDispatchContext): Promise<unknown>;
 }
+
 /** Minimal shape of an MCP client (satisfied by `@nebutra/mcp`'s `mcpClient`). */
 interface McpClientLike {
     executeTool(name: string, args: unknown, ctx: {
@@ -74,4 +75,4 @@ declare function adaptMcpTool(server: string, definition: ToolDefinition, client
     origin: ToolOrigin;
 };
 
-export { type McpClientLike, type RegisteredTool, type ToolDefinition, type ToolDispatchContext, type ToolHandler, type ToolHooks, type ToolOrigin, ToolRegistry, adaptMcpTool };
+export { type McpClientLike, type RegisteredTool, RuntimeToolRegistry, type ToolDefinition, type ToolDispatchContext, type ToolHandler, type ToolHooks, type ToolOrigin, RuntimeToolRegistry as ToolRegistry, adaptMcpTool };

package/dist/tools.js

@@ -1,9 +1,11 @@
 import {
-  ToolRegistry,
+  RuntimeToolRegistry,
   adaptMcpTool
-} from "./chunk-NN7DATXA.js";
+} from "./chunk-4Y25ZTKI.js";
+import "./chunk-424PT5DM.js";
 export {
-  ToolRegistry,
+  RuntimeToolRegistry,
+  RuntimeToolRegistry as ToolRegistry,
   adaptMcpTool
 };
 //# sourceMappingURL=tools.js.map

package/examples/pulsar-quickstart.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { InMemoryRolloutStore, Pulsar, RuntimeToolRegistry } from "../src";
+
+const tools = new RuntimeToolRegistry();
+tools.register(
+  { name: "echo", description: "Echo a value", inputSchema: z.object({ value: z.string() }) },
+  async (input: { value: string }) => input.value,
+);
+
+const pulsar = Pulsar.builder()
+  .withTenant("local")
+  .withConfig({
+    model: "local",
+    provider: "injected",
+    approvalPolicy: "on_request",
+    capabilityPolicy: "external_sandbox",
+  })
+  .withModel({
+    async invoke() {
+      return { emissions: [{ kind: "text", text: "hello from Pulsar" }] };
+    },
+  })
+  .withTools(tools)
+  .withRolloutStore(new InMemoryRolloutStore())
+  .withApprovalGate({
+    async request() {
+      return { kind: "approved" };
+    },
+  })
+  .build();
+
+const thread = await pulsar.startPlay("hello_play", "Say hello");
+for await (const event of thread.subscribe()) {
+  process.stdout.write(`${JSON.stringify(event)}\n`);
+}

package/examples/resume-branch.ts

@@ -0,0 +1,45 @@
+import { InMemoryRolloutStore, Pulsar, RuntimeToolRegistry } from "../src";
+
+const eventLog = {
+  async commit() {
+    return "event_1";
+  },
+  async branchFrom(id: string, name: string) {
+    return { name, from: id, at: new Date().toISOString() };
+  },
+};
+
+const pulsar = Pulsar.builder()
+  .withTenant("local")
+  .withConfig({
+    model: "local",
+    provider: "injected",
+    approvalPolicy: "on_request",
+    capabilityPolicy: "external_sandbox",
+  })
+  .withModel({
+    async invoke() {
+      return { emissions: [{ kind: "text", text: "branch me" }] };
+    },
+  })
+  .withTools(new RuntimeToolRegistry())
+  .withRolloutStore(new InMemoryRolloutStore())
+  .withApprovalGate({
+    async request() {
+      return { kind: "approved" };
+    },
+  })
+  .withEventLog(eventLog)
+  .build();
+
+const thread = await pulsar.startPlay("branch_play", "Run once");
+let itemId = "";
+for await (const event of thread.subscribe()) {
+  if (event.type === "item.completed") itemId = event.item.id;
+}
+
+const resumed = await pulsar.resume(thread.id);
+process.stdout.write(`${JSON.stringify({ resumed: resumed.id })}\n`);
+process.stdout.write(
+  `${JSON.stringify(await pulsar.branchFromItem(thread.id, itemId, "variant"))}\n`,
+);

package/examples/subagent-fanout.ts

@@ -0,0 +1,20 @@
+import { type Brief, costReport, fanOutSubagents } from "../src";
+
+const brief = (id: string): Brief => ({
+  id,
+  objective: `produce ${id}`,
+  outputFormat: { type: "object" },
+  allowedTools: ["read"],
+  contextRefs: [],
+  boundaries: ["do not mutate parent state"],
+  budget: { durationMs: 1_000, costUsd: 0.01, tokenLimit: 1_000 },
+});
+
+const results = await fanOutSubagents([brief("visual"), brief("copy")], async (item) => ({
+  briefId: item.id,
+  output: { ok: true },
+  usage: { inputTokens: 10, cachedInputTokens: 0, outputTokens: 2, reasoningOutputTokens: 0 },
+  durationMs: 12,
+}));
+
+process.stdout.write(`${JSON.stringify(costReport(results))}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/agent-runtime",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -14,10 +14,12 @@
     "gaps": [
       "Track-B kernel sidecar transport not yet wired",
       "Durable-turn queue binding is interface-only",
-      "Rollout store backed by in-memory reference impl only"
+      "Rollout store backed by in-memory reference impl only",
+      "Pulsar facade is runnable but still delegates model execution through injected ports"
     ],
     "featureId": "agent-runtime",
     "category": "ai",
+    "surface": "agent-runtime",
     "summary": "Multi-tenant agent-runtime grammar: thread/turn/item model, approval+capability policy, tool/MCP abstraction, event-sourced rollout, external-sandbox delegation seam"
   },
   "main": "./src/index.ts",
@@ -26,6 +28,8 @@
     ".": "./src/index.ts",
     "./model": "./src/model.ts",
     "./protocol": "./src/protocol.ts",
+    "./pulsar": "./src/pulsar.ts",
+    "./orchestration": "./src/orchestration.ts",
     "./policy": "./src/policy.ts",
     "./tools": "./src/tools.ts",
     "./rollout": "./src/rollout.ts",
@@ -36,10 +40,13 @@
     "./adapters/prisma-rollout": "./src/adapters/prisma-rollout.ts"
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "@nebutra/ai-primitives": "0.1.1",
+    "@nebutra/capability-kit": "0.2.1",
+    "@nebutra/execution-policy": "0.1.1"
   },
   "peerDependencies": {
-    "@nebutra/mcp": "0.1.1"
+    "@nebutra/mcp": "0.1.2"
   },
   "peerDependenciesMeta": {
     "@nebutra/mcp": {
@@ -51,7 +58,7 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18",
-    "@nebutra/mcp": "0.1.1"
+    "@nebutra/mcp": "0.1.2"
   },
   "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/agent-runtime#readme",
   "repository": {

package/src/cli.ts

@@ -0,0 +1,49 @@
+import { readCapabilityDebug } from "@nebutra/capability-kit/debug";
+
+const command = process.argv[2] ?? "doctor";
+
+if (command === "doctor") {
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        capability: "agent-runtime",
+        ok: true,
+        checks: ["thread-turn-item", "rollout-store", "pulsar-facade", "subagent-briefs"],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+} else if (command === "debug" || command === "replay") {
+  const threadId = process.argv[3];
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        capability: "agent-runtime",
+        threadId,
+        entries: await readCapabilityDebug("agent-runtime", { limit: 20 }),
+        suggestion:
+          "Use a RolloutStore-backed host to replay full thread events; this CLI reports local debug lines.",
+      },
+      null,
+      2,
+    )}\n`,
+  );
+} else if (command === "subagent-trace" || command === "subagent-cost") {
+  const threadId = process.argv[3];
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        capability: "agent-runtime",
+        command,
+        threadId,
+        entries: await readCapabilityDebug("agent-runtime", { limit: 20 }),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+} else {
+  process.stderr.write(`Unknown agent-runtime command: ${command}\n`);
+  process.exitCode = 1;
+}

package/src/context-compaction.ts

@@ -73,6 +73,10 @@
  * is never mutated; every transformation builds new arrays/strings.
  */
 
+import {
+  type BaseTokenEstimator,
+  estimateTokens as estimatePrimitiveTokens,
+} from "@nebutra/ai-primitives";
 import { z } from "zod";
 
 /** Tokenizers undercount real BPE by ~15-30%; scale the base estimate up. */
@@ -134,7 +138,7 @@ export type Transcript = readonly Message[];
 export type Summarize = (prompt: string) => Promise<string>;
 
 /** Caller-injected cheap token heuristic; defaults to chars/4. */
-export type BaseEstimator = (text: string) => number;
+export type BaseEstimator = BaseTokenEstimator;
 
 /** The eligibility signal this module keys on (also the failure sentinel). */
 export const COMPACT_SENTINEL = "compact";
@@ -170,7 +174,7 @@ const compactInputSchema = z.object({
  * from the model's server-side counting. Always rounds UP — see header.
  */
 export function estimateTokens(text: string, base: BaseEstimator = defaultBase): number {
-  return Math.ceil(base(text) * TOKEN_CORRECTION);
+  return estimatePrimitiveTokens(text, { base, correction: TOKEN_CORRECTION });
 }
 
 /**

package/src/index.ts

@@ -32,10 +32,12 @@ export * from "./loop";
 export * from "./mcp-bridge";
 export * from "./memory-provider";
 export * from "./model";
+export * from "./orchestration";
 export * from "./permission-ruleset";
 export * from "./policy";
 export * from "./project-repo";
 export * from "./protocol";
+export * from "./pulsar";
 export * from "./rollout";
 export * from "./rollout-store-persistent";
 export * from "./sandbox";

package/src/loop.ts

@@ -25,7 +25,7 @@ import {
 } from "./policy";
 import type { ServerRequest } from "./protocol";
 import { type RolloutLine, type RolloutStore, sanitizeForPersist } from "./rollout";
-import type { ToolDispatchContext, ToolRegistry } from "./tools";
+import type { RuntimeToolRegistry, ToolDispatchContext } from "./tools";
 
 /** A single thing the model emitted in one round. */
 export type ModelEmission =
@@ -68,7 +68,7 @@ export interface RunTurnDeps {
   readonly config: TurnConfig;
   readonly approvalPolicy: ApprovalPolicy;
   readonly model: ModelInvoker;
-  readonly tools: ToolRegistry;
+  readonly tools: RuntimeToolRegistry;
   readonly store: RolloutStore;
   readonly approvalGate: ApprovalGate;
   /** Defaults to: everything requires a prompt (safe). */

package/src/mcp-bridge.ts

@@ -13,7 +13,12 @@
 
 import { z } from "zod";
 
-import { adaptMcpTool, type McpClientLike, type ToolDefinition, type ToolRegistry } from "./tools";
+import {
+  adaptMcpTool,
+  type McpClientLike,
+  type RuntimeToolRegistry,
+  type ToolDefinition,
+} from "./tools";
 
 /**
  * Port over an MCP server catalog (satisfied by `@nebutra/mcp`'s
@@ -41,12 +46,12 @@ export interface ActivateMcpToolsResult {
 
 /**
  * List the tenant/plan-visible MCP tools, adapt each via {@link adaptMcpTool},
- * and register them into the {@link ToolRegistry}. A tool whose name is already
+ * and register them into the {@link RuntimeToolRegistry}. A tool whose name is already
  * registered is skipped (reported, never thrown). Empty/blank tenantId fails
  * closed before any catalog call.
  */
 export async function activateMcpTools(
-  registry: ToolRegistry,
+  registry: RuntimeToolRegistry,
   catalog: McpServerCatalogPort,
   client: McpClientLike,
   ctx: { tenantId: string; plan?: string },