@pattern-js/mod-agents 0.2.2 → 0.3.0-main.4a77893

package/README.md

@@ -1,9 +1,12 @@
 # @pattern-js/mod-agents
 
-The **neutral** agents contracts layer for [Pattern](../../README.md) — plain-JSON
-agent/tool/guardrail descriptors and the modality-agnostic turn event protocol,
-with **no SDK dependency**. Provider mods reify the descriptors; apps consume the
-events. Neither has to know about the other.
+[pattern-js.dev](https://pattern-js.dev) · [npm](https://www.npmjs.com/package/@pattern-js/mod-agents)
+
+The **neutral** agents layer for [Pattern](../../README.md): plain-JSON
+agent/tool/guardrail descriptors, the modality-agnostic turn event protocol, and
+the native agent run loop, with **no provider SDK**. It calls a model through a
+seam that `@pattern-js/mod-ai` implements; apps consume the events. Each layer is
+decoupled.
 
 ```bash
 npm install @pattern-js/mod-agents
@@ -11,28 +14,29 @@ npm install @pattern-js/mod-agents
 
 ## When to use
 
-Install it whenever you want agents in your app — but never *alone*. It
-contributes the `boundary.tool` pair, the toolset/guardrail ops, and the live
-tool registry (`AGENTS_SERVICE`); it does **not** run an agent. Pair it with a
-provider (`@pattern-js/mod-agents-openai`) that reifies the descriptors and emits
-the turn events.
+Install it whenever you want agents in your app, always alongside a model
+provider. It contributes the `boundary.tool` pair, the toolset/guardrail ops, the
+live tool registry (`AGENTS_SERVICE`), and **the native agent run loop**; the loop
+needs a model to run. Pair it with `@pattern-js/mod-ai` (the model provider: it
+implements the neutral model seam this loop calls and adds the `ai.model` node +
+capability ops).
 
 **When not:** a single model call with no tools, no agent loop, and no streaming
-turn events — a provider op straight from the canvas is lighter than the agents
-stack.
+turn events. An `ai.text.generate` op straight from the canvas is lighter than
+the agents stack.
 
 ## Prerequisites
 
-Always ship it with a provider. Usually also `@pattern-js/mod-store` (history +
-blobs) and `@pattern-js/mod-vault` (the API key).
+Always ship it with `@pattern-js/mod-ai` (the model provider). Usually also
+`@pattern-js/mod-store` (history + blobs) and `@pattern-js/mod-vault` (provider keys).
 
 ## Config
 
-The contracts always ship paired with a provider — add both as strings in
-`pattern.config.json`:
+The agents layer always ships paired with the model provider. Add both as strings
+in `pattern.config.json`:
 
 ```jsonc
-{ "mods": ["@pattern-js/mod-agents", "@pattern-js/mod-agents-openai"] }
+{ "mods": ["@pattern-js/mod-agents", "@pattern-js/mod-ai"] }
 ```
 
 For options, export a local wrapper mod that calls the `agentsMod({...})` factory.

package/dist/agent-ops.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @pattern-js/mod-agents — the agent ops, re-hosted natively.
+ *
+ * `agents.agent` builds a DESCRIPTOR (plain JSON, no model work). `agents.run`
+ * drives the native loop over the neutral model service (mod-ai), streaming the
+ * turn-event protocol while `output`/`history` settle as values. History is
+ * explicit: pull it from a store node, push the updated one back. Pre-flight
+ * problems (no model provider) FAIL the node loudly; mid-turn problems (rate
+ * limits, guardrail trips) become turn events and a soft outcome.
+ */
+import { type OpDefinition } from "@pattern-js/core";
+export declare const agentRunOps: OpDefinition[];
+//# sourceMappingURL=agent-ops.d.ts.map

package/dist/agent-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-ops.d.ts","sourceRoot":"","sources":["../src/agent-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAA8C,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA6SjG,eAAO,MAAM,WAAW,EAAE,YAAY,EAAiD,CAAC"}

package/dist/agent-ops.js

@@ -0,0 +1,271 @@
+/**
+ * @pattern-js/mod-agents — the agent ops, re-hosted natively.
+ *
+ * `agents.agent` builds a DESCRIPTOR (plain JSON, no model work). `agents.run`
+ * drives the native loop over the neutral model service (mod-ai), streaming the
+ * turn-event protocol while `output`/`history` settle as values. History is
+ * explicit: pull it from a store node, push the updated one back. Pre-flight
+ * problems (no model provider) FAIL the node loudly; mid-turn problems (rate
+ * limits, guardrail trips) become turn events and a soft outcome.
+ */
+import { required, stream, value, z } from "@pattern-js/core";
+import { agentsService } from "./well-known.js";
+import { aiModelService } from "./model-service.js";
+import { startTurn, decodeState } from "./loop.js";
+import { agentSchema, historySchema, messagePartSchema, modelRefSchema, toolsetSchema, turnEventSchema, } from "./types.js";
+async function maybe(ctx, port) {
+    return ctx.input.has(port) ? (await ctx.input.value(port)) : undefined;
+}
+const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+/* ── agents.agent ──────────────────────────────────────────────────────── */
+const agentOp = {
+    type: "agents.agent",
+    title: "agents.agent",
+    description: "Define an agent (a value you wire into agents.run, a handoff, or a tool). Wire a model from ai.model; " +
+        "name/instructions default to config but can be wired at runtime to vary them per request (a wired value " +
+        "overrides config); tools/guardrails/handoffs wire in as inputs. No model = the configured default.",
+    config: z.object({
+        name: z.string().min(1),
+        /** The system prompt: what this agent does and how it answers. */
+        instructions: z.string().min(1),
+        /** Shown to other agents deciding whether to hand off to this one. */
+        handoffDescription: z.string().optional(),
+    }),
+    inputs: {
+        // name + instructions are config by default but ALSO wireable at runtime —
+        // a wired value (even one derived from the request) overrides the config, so
+        // a pipeline can vary an agent's identity per turn (e.g. chat's voice mode
+        // swaps in spoken-style instructions). Unwired ⇒ the config value stands.
+        name: value(z.string()),
+        instructions: value(z.string()),
+        model: value(modelRefSchema),
+        tools: value(toolsetSchema),
+        guardrails: value(), // GuardrailDescriptor | GuardrailDescriptor[]
+        handoffs: value(), // AgentDescriptor | AgentDescriptor[]
+    },
+    outputs: { agent: value(agentSchema) },
+    execute: async (ctx) => {
+        const cfg = ctx.config;
+        const [nameIn, instructionsIn, model, tools, guardrailsIn, handoffsIn] = await Promise.all([
+            maybe(ctx, "name"),
+            maybe(ctx, "instructions"),
+            maybe(ctx, "model"),
+            maybe(ctx, "tools"),
+            maybe(ctx, "guardrails"),
+            maybe(ctx, "handoffs"),
+        ]);
+        const guardrails = asArray(guardrailsIn);
+        const handoffs = asArray(handoffsIn).map((h) => agentSchema.parse(h));
+        const agent = {
+            kind: "agent",
+            name: nameIn ?? cfg.name,
+            instructions: instructionsIn ?? cfg.instructions,
+            model: model ? modelRefSchema.parse(model) : undefined,
+            handoffDescription: cfg.handoffDescription,
+            tools,
+            guardrails: guardrails.length ? guardrails : undefined,
+            handoffs: handoffs.length ? handoffs : undefined,
+        };
+        return { agent };
+    },
+};
+/* ── run plumbing ──────────────────────────────────────────────────────── */
+const runOutputs = {
+    events: stream(turnEventSchema),
+    output: value(),
+    history: value(historySchema),
+    stopReason: value(z.enum(["complete", "interrupted", "error", "cancelled"])),
+    stateToken: value(z.string().nullable()),
+};
+function softOutputs(outcome) {
+    return {
+        output: outcome.then((o) => o.output),
+        history: outcome.then((o) => o.history ?? []),
+        stopReason: outcome.then((o) => o.stopReason),
+        stateToken: outcome.then((o) => o.stateToken),
+    };
+}
+/**
+ * Turn-scoped abort: a STREAMING run settles for the engine before the turn
+ * finishes (the SSE tail flows after result-ready), so engine.cancelRun can't
+ * reach it — a Stop button aborts via AGENTS_SERVICE.abortTurn(turnId). The
+ * run-level ctx.signal still chains in (editor Stop, sub-runs).
+ */
+function turnAbort(ctx, turnId) {
+    const ctrl = new AbortController();
+    const svc = agentsService(ctx);
+    svc.registerTurn(turnId, ctrl);
+    return { signal: AbortSignal.any([ctx.signal, ctrl.signal]), release: () => svc.releaseTurn(turnId) };
+}
+function looksLikeParts(v) {
+    return Array.isArray(v) && v.length > 0 && v.every((p) => messagePartSchema.safeParse(p).success);
+}
+/** Shape the user turn: string | parts → one user message; neutral items pass through. */
+function userMessages(input) {
+    if (typeof input === "string")
+        return [{ role: "user", content: input }];
+    if (looksLikeParts(input))
+        return [{ role: "user", content: input }];
+    if (Array.isArray(input))
+        return input;
+    throw new Error("agents.run: input must be a string, a parts array, or neutral messages");
+}
+const DEFAULT_MAX_TURNS = 10;
+/* ── agents.run ────────────────────────────────────────────────────────── */
+const runOp = {
+    type: "agents.run",
+    title: "agents.run",
+    description: "Run an agent: input (text or parts) + optional history in → turn events stream + final output + updated history out. " +
+        "Tool calls are linked sub-runs; the events stream always terminates with `done`.",
+    config: z.object({ maxTurns: z.number().int().positive().optional() }),
+    inputs: {
+        agent: required(agentSchema),
+        input: required(),
+        history: value(historySchema),
+        turnId: value(z.string()),
+    },
+    outputs: runOutputs,
+    execute: async (ctx) => {
+        const [descRaw, input, history, turnId] = await Promise.all([
+            ctx.input.value("agent"),
+            ctx.input.value("input"),
+            maybe(ctx, "history"),
+            maybe(ctx, "turnId"),
+        ]);
+        const model = aiModelService(ctx); // pre-flight: loud if no provider
+        const descriptor = agentSchema.parse(descRaw);
+        const messages = [...(history ?? []), ...userMessages(input)];
+        const { maxTurns } = ctx.config;
+        const tid = turnId ?? ctx.runId;
+        const { signal, release } = turnAbort(ctx, tid);
+        const { events, outcome } = startTurn({
+            ctx,
+            model,
+            descriptor,
+            messages,
+            maxTurns: maxTurns ?? DEFAULT_MAX_TURNS,
+            ids: { turnId: tid, runId: ctx.runId },
+            signal,
+        });
+        void outcome.finally(release);
+        return { events, ...softOutputs(outcome) };
+    },
+};
+/* ── agents.run.resume (HITL) ──────────────────────────────────────────── */
+const resumeOp = {
+    type: "agents.run.resume",
+    title: "agents.run.resume",
+    description: "Resume an interrupted run (HITL): the stateToken from approval.request + approve/reject decisions → the turn continues streaming.",
+    config: z.object({}),
+    inputs: {
+        agent: required(agentSchema),
+        stateToken: required(z.string()),
+        /** [{ id, approved }] (or one object) matching approval.request interruptions. */
+        decisions: required(),
+        turnId: value(z.string()),
+    },
+    outputs: runOutputs,
+    execute: async (ctx) => {
+        const [descRaw, stateToken, decisionsIn, turnId] = await Promise.all([
+            ctx.input.value("agent"),
+            ctx.input.value("stateToken"),
+            ctx.input.value("decisions"),
+            maybe(ctx, "turnId"),
+        ]);
+        const model = aiModelService(ctx);
+        const descriptor = agentSchema.parse(descRaw);
+        const saved = decodeState(stateToken);
+        const decisions = asArray(decisionsIn);
+        const tid = turnId ?? ctx.runId;
+        const { signal, release } = turnAbort(ctx, tid);
+        const { events, outcome } = startTurn({
+            ctx,
+            model,
+            descriptor,
+            messages: saved.messages,
+            maxTurns: DEFAULT_MAX_TURNS,
+            ids: { turnId: tid, runId: ctx.runId },
+            signal,
+            resume: { saved, decisions },
+        });
+        void outcome.finally(release);
+        return { events, ...softOutputs(outcome) };
+    },
+};
+/* ── agents.history.compact ────────────────────────────────────────────── */
+const compactOp = {
+    type: "agents.history.compact",
+    title: "agents.history.compact",
+    description: "Squeeze a long history: items beyond keepRecent are summarized into one message (a visible node, so you SEE when memory compresses). Wire a model from ai.model or use the default.",
+    config: z.object({
+        /** Compact only when the history exceeds this many items. */
+        threshold: z.number().int().positive().default(60),
+        /** Most-recent items kept verbatim. */
+        keepRecent: z.number().int().positive().default(20),
+    }),
+    inputs: { history: required(historySchema), model: value(modelRefSchema) },
+    outputs: { history: value(historySchema), compacted: value(z.boolean()) },
+    execute: async (ctx) => {
+        const cfg = ctx.config;
+        const [history, modelRef] = await Promise.all([
+            ctx.input.value("history"),
+            maybe(ctx, "model"),
+        ]);
+        if (history.length <= cfg.threshold)
+            return { history, compacted: false };
+        const old = history.slice(0, history.length - cfg.keepRecent);
+        const recent = history.slice(history.length - cfg.keepRecent);
+        const model = aiModelService(ctx);
+        const { text } = await model.generateText({
+            ctx,
+            modelRef,
+            system: "Summarize the following conversation log into a compact brief that preserves facts, names, decisions and open tasks. Reply with the summary only.",
+            messages: [{ role: "user", content: JSON.stringify(old) }],
+            signal: ctx.signal,
+        });
+        const summaryItem = { role: "user", content: `[Summary of the earlier conversation]\n${text}` };
+        ctx.log("info", "history compacted", { from: history.length, to: recent.length + 1 });
+        return { history: [summaryItem, ...recent], compacted: true };
+    },
+};
+/* ── agents.mcp.client ─────────────────────────────────────────────────── */
+const mcpOp = {
+    type: "agents.mcp.client",
+    title: "agents.mcp.client",
+    description: "Connect to an MCP server and expose its tools as a toolset value (connection pooled by mod-ai). http: url (+headers) · stdio: command (+args). " +
+        'For stdio you can paste a WHOLE command line into `command` (e.g. "docker mcp gateway run --profile X"); it is ' +
+        "tokenized automatically; `args` are appended.",
+    config: z.object({
+        transport: z.enum(["http", "stdio"]).default("http"),
+        url: z.string().optional(),
+        command: z.string().optional(),
+        args: z.array(z.string()).optional(),
+        serverLabel: z.string().optional(),
+    }),
+    inputs: {
+        /** Auth headers for http transport — wire vault.read into a builder. */
+        headers: value(z.record(z.string(), z.string())),
+    },
+    outputs: { toolset: value(toolsetSchema) },
+    execute: async (ctx) => {
+        const cfg = ctx.config;
+        const headers = await maybe(ctx, "headers");
+        const toolset = {
+            kind: "toolset",
+            tools: [
+                {
+                    origin: "mcp",
+                    transport: cfg.transport,
+                    url: cfg.url,
+                    headers,
+                    command: cfg.command,
+                    args: cfg.args,
+                    serverLabel: cfg.serverLabel,
+                },
+            ],
+        };
+        return { toolset };
+    },
+};
+export const agentRunOps = [agentOp, runOp, resumeOp, compactOp, mcpOp];
+//# sourceMappingURL=agent-ops.js.map

package/dist/agent-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-ops.js","sourceRoot":"","sources":["../src/agent-ops.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -5,5 +5,8 @@ export { AGENTS_SERVICE, agentsService, workflowToolRef, type AgentsService, typ
 export { AgentsRegistry } from "./service.js";
 export { agentBoundaryOps, toolTrigger, toolReturn } from "./boundaries.js";
 export { agentsOps } from "./ops.js";
-export { agentSchema, guardrailSchema, historySchema, messagePartSchema, toolRefSchema, toolsetSchema, turnEventSchema, type AgentDescriptor, type GuardrailDescriptor, type History, type MessagePart, type ToolRef, type ToolsetDescriptor, type TurnEvent, type TurnStopReason, } from "./types.js";
+export { agentRunOps } from "./agent-ops.js";
+export { agentSchema, guardrailSchema, historySchema, messagePartSchema, modelRefSchema, neutralMessageSchema, toolRefSchema, toolsetSchema, turnEventSchema, usageSchema, type AgentDescriptor, type GuardrailDescriptor, type History, type MessagePart, type ModelRef, type NeutralMessage, type ToolRef, type ToolsetDescriptor, type TurnEvent, type TurnStopReason, type Usage, } from "./types.js";
+export { AI_MCP_SERVICE, AI_MODEL_SERVICE, aiMcpService, aiModelService, type AiMcpService, type AiModelService, type GenerateTextInput, type McpToolRef, type NeutralChunk, type NeutralToolDef, type StreamTurnInput, } from "./model-service.js";
+export { startTurn, decodeState, type Decision, type TurnOutcome } from "./loop.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,eAAe,EACf,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,KAAK,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -5,5 +5,8 @@ export { AGENTS_SERVICE, agentsService, workflowToolRef, } from "./well-known.js
 export { AgentsRegistry } from "./service.js";
 export { agentBoundaryOps, toolTrigger, toolReturn } from "./boundaries.js";
 export { agentsOps } from "./ops.js";
-export { agentSchema, guardrailSchema, historySchema, messagePartSchema, toolRefSchema, toolsetSchema, turnEventSchema, } from "./types.js";
+export { agentRunOps } from "./agent-ops.js";
+export { agentSchema, guardrailSchema, historySchema, messagePartSchema, modelRefSchema, neutralMessageSchema, toolRefSchema, toolsetSchema, turnEventSchema, usageSchema, } from "./types.js";
+export { AI_MCP_SERVICE, AI_MODEL_SERVICE, aiMcpService, aiModelService, } from "./model-service.js";
+export { startTurn, decodeState } from "./loop.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,GAIhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,eAAe,GAShB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,GAIhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,eAAe,EACf,WAAW,GAYZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,cAAc,GAQf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAmC,MAAM,WAAW,CAAC"}

package/dist/loop.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @pattern-js/mod-agents — the native agent run loop.
+ *
+ * Replaces the @openai/agents Runner: we drive the model↔tool turn loop
+ * ourselves over the neutral AiModelService (mod-ai implements it). Each model
+ * step is a single `streamTurn` call; THIS loop owns multi-step. Tools are
+ * linked sub-runs (`ctx.invoke`) / op-registry calls / MCP; handoffs swap the
+ * active agent; guardrails are tool sub-runs; HITL pauses with a stateToken.
+ *
+ * It emits the neutral `turnEventSchema` and the produced stream ALWAYS
+ * terminates with a `done` event — complete | interrupted | error | cancelled.
+ */
+import type { OpContext } from "@pattern-js/core";
+import { type AiModelService } from "./model-service.js";
+import type { AgentDescriptor, NeutralMessage, TurnEvent, TurnStopReason } from "./types.js";
+interface Ids {
+    turnId: string;
+    runId: string;
+}
+export interface TurnOutcome {
+    stopReason: TurnStopReason;
+    /** Final text/structured output; null on error/interruption/cancel. */
+    output: unknown;
+    /** Full neutral history after the run; null on hard failure/cancel. */
+    history: NeutralMessage[] | null;
+    /** Serialized loop state when interrupted (HITL resume token). */
+    stateToken: string | null;
+}
+export interface Decision {
+    id: string;
+    approved: boolean;
+}
+/** A pending tool call buffered for human approval. */
+interface Pending {
+    callId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+/** The serialized HITL state (opaque to consumers; this loop owns the shape). */
+interface SavedState {
+    messages: NeutralMessage[];
+    activeAgent: string;
+    pending: Pending[];
+}
+declare const decodeState: (t: string) => SavedState;
+export interface StartTurnParams {
+    ctx: OpContext;
+    model: AiModelService;
+    descriptor: AgentDescriptor;
+    /** Conversation so far (history + the new user turn). */
+    messages: NeutralMessage[];
+    maxTurns: number;
+    ids: Ids;
+    signal: AbortSignal;
+    /** Resume path: decisions to apply against the saved pending approvals. */
+    resume?: {
+        saved: SavedState;
+        decisions: Decision[];
+    };
+}
+/**
+ * Run an agent turn (fresh or resumed). Returns the neutral event stream plus a
+ * settled outcome. Mirrors the old `pumpTurn` contract: the stream never
+ * rejects and always closes with `done`.
+ */
+export declare function startTurn(params: StartTurnParams): {
+    events: ReadableStream<TurnEvent>;
+    outcome: Promise<TurnOutcome>;
+};
+/** Re-expose the saved state shape for the resume op. */
+export { decodeState };
+//# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAgB,KAAK,cAAc,EAAuB,MAAM,oBAAoB,CAAC;AAC5F,OAAO,KAAK,EACV,eAAe,EAGf,cAAc,EAEd,SAAS,EACT,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,UAAU,GAAG;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,cAAc,CAAC;IAC3B,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACjC,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,uDAAuD;AACvD,UAAU,OAAO;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,iFAAiF;AACjF,UAAU,UAAU;IAClB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,EAAE,CAAC;CACpB;AAGD,QAAA,MAAM,WAAW,GAAI,GAAG,MAAM,KAAG,UAAyC,CAAC;AA6G3E,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,EAAE,eAAe,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,WAAW,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;CACvD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG;IAClD,MAAM,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/B,CA0KA;AAED,yDAAyD;AACzD,OAAO,EAAE,WAAW,EAAE,CAAC"}