@polpo-ai/core 0.8.0 → 0.9.0

package/dist/loop/runner.js

@@ -0,0 +1,215 @@
+import { SafeExpressionEvaluator } from "./expression.js";
+import { LoopHookRegistry, } from "./hooks.js";
+const DEFAULT_MAX_TURNS = 20;
+function normalizeLoop(loop) {
+    return {
+        ...loop,
+        name: loop.name ?? "default",
+    };
+}
+function shouldStopAfterTurn(loop, context, result, turn, maxTurns, evaluator) {
+    const reachedMaxTurns = turn + 1 >= maxTurns;
+    if (loop.stopWhen) {
+        const matched = evaluator.evaluate(loop.stopWhen.expression, context);
+        if (matched)
+            return { reason: "completed", shouldStop: true };
+        return reachedMaxTurns ? { reason: "max_turns", shouldStop: true } : { reason: "completed", shouldStop: false };
+    }
+    if ((result.toolCalls ?? []).length === 0)
+        return { reason: "completed", shouldStop: true };
+    if (reachedMaxTurns)
+        return { reason: "max_turns", shouldStop: true };
+    return { reason: "completed", shouldStop: false };
+}
+export class LoopRunner {
+    hooks;
+    evaluator = new SafeExpressionEvaluator();
+    constructor(hooks) {
+        this.hooks = hooks ?? new LoopHookRegistry();
+    }
+    async run(options) {
+        const hooks = options.hooks ?? this.hooks;
+        const loop = normalizeLoop(options.loop);
+        const context = options.context ?? {};
+        const maxTurns = options.maxTurns ?? loop.maxTurns ?? DEFAULT_MAX_TURNS;
+        let finalText = "";
+        let turns = 0;
+        const allToolResults = [];
+        const start = await hooks.runBefore("loop:start", {
+            agent: options.agent,
+            loop,
+            context,
+            input: options.input,
+        });
+        if (start.cancelled) {
+            return this.finish(hooks, {
+                agent: options.agent,
+                loop,
+                context,
+                status: "cancelled",
+                reason: "cancelled",
+                turns,
+                text: finalText,
+                toolResults: allToolResults,
+            });
+        }
+        for (let turn = 0; turn < maxTurns; turn++) {
+            turns = turn + 1;
+            const step = await hooks.runBefore("step:before", {
+                agent: options.agent,
+                loop,
+                turn,
+                context,
+                activeTools: loop.tools,
+            });
+            if (step.cancelled) {
+                return this.finish(hooks, {
+                    agent: options.agent,
+                    loop,
+                    context,
+                    status: "cancelled",
+                    reason: "cancelled",
+                    turns,
+                    text: finalText,
+                    toolResults: allToolResults,
+                });
+            }
+            const modelBefore = await hooks.runBefore("model:before", {
+                agent: options.agent,
+                loop,
+                turn,
+                context,
+                activeTools: step.data.activeTools,
+                toolChoice: step.data.toolChoice,
+            });
+            if (modelBefore.cancelled) {
+                return this.finish(hooks, {
+                    agent: options.agent,
+                    loop,
+                    context,
+                    status: "cancelled",
+                    reason: "cancelled",
+                    turns,
+                    text: finalText,
+                    toolResults: allToolResults,
+                });
+            }
+            const modelInput = {
+                agent: options.agent,
+                loop,
+                turn,
+                context,
+                activeTools: modelBefore.data.activeTools,
+                toolChoice: modelBefore.data.toolChoice,
+            };
+            const modelResult = await options.model(modelInput);
+            finalText += modelResult.text;
+            const toolResults = [];
+            for (const rawCall of modelResult.toolCalls ?? []) {
+                const before = await hooks.runBefore("tool:before", {
+                    agent: options.agent,
+                    loop,
+                    turn,
+                    context,
+                    toolCall: { ...rawCall, args: { ...rawCall.args } },
+                });
+                const toolCall = before.data.toolCall;
+                const skipped = before.cancelled;
+                const result = skipped
+                    ? before.data.result ?? `Error: Tool call "${toolCall.name}" denied${before.cancelReason ? `: ${before.cancelReason}` : ""}`
+                    : await options.executeTool(toolCall, modelInput);
+                const toolResult = {
+                    toolCall,
+                    result,
+                    isError: result.startsWith("Error:"),
+                    skipped,
+                };
+                toolResults.push(toolResult);
+                allToolResults.push(toolResult);
+                await hooks.runAfter("tool:after", {
+                    agent: options.agent,
+                    loop,
+                    turn,
+                    context,
+                    toolCall,
+                    result,
+                    isError: toolResult.isError,
+                    skipped,
+                });
+            }
+            await hooks.runAfter("step:after", {
+                agent: options.agent,
+                loop,
+                turn,
+                context,
+                text: modelResult.text,
+                toolCalls: modelResult.toolCalls ?? [],
+                toolResults,
+                usage: modelResult.usage,
+            });
+            const stop = shouldStopAfterTurn(loop, context, modelResult, turn, maxTurns, this.evaluator);
+            const stopResult = await hooks.runBefore("loop:stop", {
+                agent: options.agent,
+                loop,
+                turn,
+                context,
+                reason: stop.reason,
+                shouldStop: stop.shouldStop,
+            });
+            if (stopResult.cancelled) {
+                return this.finish(hooks, {
+                    agent: options.agent,
+                    loop,
+                    context,
+                    status: "cancelled",
+                    reason: "cancelled",
+                    turns,
+                    text: finalText,
+                    toolResults: allToolResults,
+                });
+            }
+            if (stopResult.data.shouldStop) {
+                return this.finish(hooks, {
+                    agent: options.agent,
+                    loop,
+                    context,
+                    status: "completed",
+                    reason: stopResult.data.reason,
+                    turns,
+                    text: finalText,
+                    toolResults: allToolResults,
+                });
+            }
+        }
+        return this.finish(hooks, {
+            agent: options.agent,
+            loop,
+            context,
+            status: "completed",
+            reason: "max_turns",
+            turns,
+            text: finalText,
+            toolResults: allToolResults,
+        });
+    }
+    async finish(hooks, result) {
+        await hooks.runAfter("loop:end", {
+            agent: result.agent,
+            loop: result.loop,
+            context: result.context,
+            status: result.status,
+            reason: result.reason,
+            turns: result.turns,
+            text: result.text,
+        });
+        return {
+            status: result.status,
+            reason: result.reason,
+            turns: result.turns,
+            text: result.text,
+            context: result.context,
+            toolResults: result.toolResults,
+        };
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/loop/runner.js.map

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

package/dist/loop/runner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runner.test.d.ts.map

package/dist/loop/runner.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.test.d.ts","sourceRoot":"","sources":["../../src/loop/runner.test.ts"],"names":[],"mappings":""}

package/dist/loop/runner.test.js

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { LoopHookRegistry } from "./hooks.js";
+import { LoopRunner } from "./runner.js";
+describe("LoopRunner", () => {
+    it("runs the implicit loop with ordered lifecycle hooks", async () => {
+        const events = [];
+        const hooks = new LoopHookRegistry();
+        hooks.register({ hook: "loop:start", phase: "before", handler: () => { events.push("loop:start"); } });
+        hooks.register({ hook: "step:before", phase: "before", handler: () => { events.push("step:before"); } });
+        hooks.register({ hook: "model:before", phase: "before", handler: () => { events.push("model:before"); } });
+        hooks.register({ hook: "step:after", phase: "after", handler: () => { events.push("step:after"); } });
+        hooks.register({ hook: "loop:stop", phase: "before", handler: () => { events.push("loop:stop"); } });
+        hooks.register({ hook: "loop:end", phase: "after", handler: () => { events.push("loop:end"); } });
+        const runner = new LoopRunner(hooks);
+        const result = await runner.run({
+            loop: { name: "default" },
+            model: async () => ({ text: "done" }),
+            executeTool: async () => "unused",
+        });
+        expect(result).toMatchObject({ status: "completed", reason: "completed", turns: 1, text: "done" });
+        expect(events).toEqual(["loop:start", "step:before", "model:before", "step:after", "loop:stop", "loop:end"]);
+    });
+    it("lets step hooks constrain active tools before the model call", async () => {
+        const hooks = new LoopHookRegistry();
+        hooks.register({
+            hook: "step:before",
+            phase: "before",
+            handler: (ctx) => {
+                ctx.data.activeTools = ["read"];
+            },
+        });
+        const seenTools = [];
+        const runner = new LoopRunner(hooks);
+        await runner.run({
+            loop: { name: "plan", tools: ["read", "write"] },
+            model: async (input) => {
+                seenTools.push(input.activeTools);
+                return { text: "planned" };
+            },
+            executeTool: async () => "unused",
+        });
+        expect(seenTools).toEqual([["read"]]);
+    });
+    it("allows tool:before hooks to deny a tool call without invoking the executor", async () => {
+        const hooks = new LoopHookRegistry();
+        hooks.register({
+            hook: "tool:before",
+            phase: "before",
+            handler: (ctx) => {
+                if (ctx.data.toolCall.name === "write")
+                    ctx.cancel("read-only loop");
+            },
+        });
+        let executed = false;
+        const runner = new LoopRunner(hooks);
+        const result = await runner.run({
+            loop: { name: "plan", tools: ["read"] },
+            maxTurns: 1,
+            model: async () => ({
+                text: "I will write.",
+                toolCalls: [{ id: "call-1", name: "write", args: { path: "x.txt" } }],
+            }),
+            executeTool: async () => {
+                executed = true;
+                return "should not run";
+            },
+        });
+        expect(executed).toBe(false);
+        expect(result.toolResults).toHaveLength(1);
+        expect(result.toolResults[0]).toMatchObject({
+            skipped: true,
+            isError: true,
+            result: 'Error: Tool call "write" denied: read-only loop',
+        });
+    });
+    it("continues when loop:stop mutates shouldStop to false", async () => {
+        const hooks = new LoopHookRegistry();
+        hooks.register({
+            hook: "loop:stop",
+            phase: "before",
+            handler: (ctx) => {
+                if (ctx.data.turn === 0)
+                    ctx.data.shouldStop = false;
+            },
+        });
+        let calls = 0;
+        const runner = new LoopRunner(hooks);
+        const result = await runner.run({
+            loop: { name: "review" },
+            maxTurns: 2,
+            model: async () => {
+                calls++;
+                return { text: String(calls) };
+            },
+            executeTool: async () => "unused",
+        });
+        expect(result.text).toBe("12");
+        expect(result.turns).toBe(2);
+        expect(result.reason).toBe("completed");
+    });
+    it("uses stopWhen as the deterministic stop condition when configured", async () => {
+        const hooks = new LoopHookRegistry();
+        hooks.register({
+            hook: "step:after",
+            phase: "after",
+            handler: (ctx) => {
+                if (ctx.data.turn === 1)
+                    ctx.data.context.done = true;
+            },
+        });
+        const runner = new LoopRunner(hooks);
+        const result = await runner.run({
+            loop: { name: "build", stopWhen: { expression: "done == true" } },
+            maxTurns: 3,
+            model: async () => ({ text: "tick" }),
+            executeTool: async () => "unused",
+        });
+        expect(result.text).toBe("ticktick");
+        expect(result.turns).toBe(2);
+        expect(result.reason).toBe("completed");
+        expect(result.context.done).toBe(true);
+    });
+});
+//# sourceMappingURL=runner.test.js.map

package/dist/loop/runner.test.js.map

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

package/dist/loop/selector.d.ts

@@ -0,0 +1,12 @@
+import type { AgentConfig } from "../types.js";
+import type { LoopConfig } from "./types.js";
+export interface LoopSelection {
+    name: string;
+    loop: LoopConfig & {
+        name: string;
+    };
+    agent: AgentConfig;
+}
+export declare function resolveActiveLoopTools(agent: AgentConfig, loop?: LoopConfig): string[] | undefined;
+export declare function resolveLoopSelection(agent: AgentConfig, requestedLoop?: string): LoopSelection;
+//# sourceMappingURL=selector.d.ts.map

package/dist/loop/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/loop/selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,EAAE,GAAG,SAAS,CAElG;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,aAAa,CAwB9F"}

package/dist/loop/selector.js

@@ -0,0 +1,44 @@
+export function resolveActiveLoopTools(agent, loop) {
+    return loop?.tools ?? agent.allowedTools;
+}
+export function resolveLoopSelection(agent, requestedLoop) {
+    if (!requestedLoop) {
+        const defaultLoop = agent.loops?.default;
+        if (!defaultLoop) {
+            return {
+                name: "default",
+                loop: { name: "default", tools: agent.allowedTools, model: agent.model, reasoning: agent.reasoning, maxTurns: agent.maxTurns },
+                agent,
+            };
+        }
+        return materializeLoopSelection(agent, "default", defaultLoop);
+    }
+    const loop = agent.loops?.[requestedLoop];
+    if (!loop) {
+        const available = Object.keys(agent.loops ?? {});
+        throw new Error(available.length > 0
+            ? `Unknown loop "${requestedLoop}". Available loops: ${available.join(", ")}`
+            : `Agent "${agent.name}" does not define configurable loops`);
+    }
+    return materializeLoopSelection(agent, requestedLoop, loop);
+}
+function materializeLoopSelection(agent, name, loop) {
+    const loopWithName = { ...loop, name: loop.name ?? name };
+    const loopPrompt = loop.systemPrompt?.trim();
+    const systemPrompt = loopPrompt
+        ? [agent.systemPrompt, `## Active loop: ${loopWithName.name}`, loopPrompt].filter(Boolean).join("\n\n")
+        : agent.systemPrompt;
+    return {
+        name: loopWithName.name,
+        loop: loopWithName,
+        agent: {
+            ...agent,
+            systemPrompt,
+            allowedTools: resolveActiveLoopTools(agent, loop),
+            model: loop.model ?? agent.model,
+            reasoning: loop.reasoning ?? agent.reasoning,
+            maxTurns: loop.maxTurns ?? agent.maxTurns,
+        },
+    };
+}
+//# sourceMappingURL=selector.js.map

package/dist/loop/selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../../src/loop/selector.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,sBAAsB,CAAC,KAAkB,EAAE,IAAiB;IAC1E,OAAO,IAAI,EAAE,KAAK,IAAI,KAAK,CAAC,YAAY,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAkB,EAAE,aAAsB;IAC7E,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC;QACzC,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,YAAY,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE;gBAC9H,KAAK;aACN,CAAC;QACJ,CAAC;QACD,OAAO,wBAAwB,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,aAAa,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QACjD,MAAM,IAAI,KAAK,CACb,SAAS,CAAC,MAAM,GAAG,CAAC;YAClB,CAAC,CAAC,iBAAiB,aAAa,uBAAuB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YAC7E,CAAC,CAAC,UAAU,KAAK,CAAC,IAAI,sCAAsC,CAC/D,CAAC;IACJ,CAAC;IAED,OAAO,wBAAwB,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,wBAAwB,CAAC,KAAkB,EAAE,IAAY,EAAE,IAAgB;IAClF,MAAM,YAAY,GAAG,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;IAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;IAC7C,MAAM,YAAY,GAAG,UAAU;QAC7B,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,mBAAmB,YAAY,CAAC,IAAI,EAAE,EAAE,UAAU,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;QACvG,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC;IAEvB,OAAO;QACL,IAAI,EAAE,YAAY,CAAC,IAAI;QACvB,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE;YACL,GAAG,KAAK;YACR,YAAY;YACZ,YAAY,EAAE,sBAAsB,CAAC,KAAK,EAAE,IAAI,CAAC;YACjD,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK;YAChC,SAAS,EAAG,IAAI,CAAC,SAAwC,IAAI,KAAK,CAAC,SAAS;YAC5E,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ;SAC1C;KACF,CAAC;AACJ,CAAC"}

package/dist/loop/selector.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=selector.test.d.ts.map

package/dist/loop/selector.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.test.d.ts","sourceRoot":"","sources":["../../src/loop/selector.test.ts"],"names":[],"mappings":""}

package/dist/loop/selector.test.js

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { resolveLoopSelection } from "./selector.js";
+describe("resolveLoopSelection", () => {
+    it("keeps current agent behavior when no loop is requested", () => {
+        const agent = { name: "agent", model: "base", allowedTools: ["read"], systemPrompt: "base" };
+        const selected = resolveLoopSelection(agent);
+        expect(selected.name).toBe("default");
+        expect(selected.agent).toBe(agent);
+    });
+    it("applies requested loop overrides to the effective agent", () => {
+        const selected = resolveLoopSelection({
+            name: "agent",
+            model: "base",
+            reasoning: "low",
+            allowedTools: ["read", "write"],
+            systemPrompt: "base prompt",
+            loops: {
+                plan: {
+                    systemPrompt: "plan prompt",
+                    tools: ["read"],
+                    model: "planner",
+                    reasoning: "high",
+                    maxTurns: 3,
+                },
+            },
+        }, "plan");
+        expect(selected.loop.name).toBe("plan");
+        expect(selected.agent).toMatchObject({
+            model: "planner",
+            reasoning: "high",
+            allowedTools: ["read"],
+            maxTurns: 3,
+        });
+        expect(selected.agent.systemPrompt).toContain("base prompt");
+        expect(selected.agent.systemPrompt).toContain("## Active loop: plan");
+        expect(selected.agent.systemPrompt).toContain("plan prompt");
+    });
+    it("throws a clear error for unknown requested loops", () => {
+        expect(() => resolveLoopSelection({
+            name: "agent",
+            loops: { plan: {} },
+        }, "build")).toThrow('Unknown loop "build". Available loops: plan');
+    });
+});
+//# sourceMappingURL=selector.test.js.map

package/dist/loop/selector.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.test.js","sourceRoot":"","sources":["../../src/loop/selector.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;QAC7F,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAE7C,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,QAAQ,GAAG,oBAAoB,CAAC;YACpC,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,MAAM;YACb,SAAS,EAAE,KAAK;YAChB,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;YAC/B,YAAY,EAAE,aAAa;YAC3B,KAAK,EAAE;gBACL,IAAI,EAAE;oBACJ,YAAY,EAAE,aAAa;oBAC3B,KAAK,EAAE,CAAC,MAAM,CAAC;oBACf,KAAK,EAAE,SAAS;oBAChB,SAAS,EAAE,MAAM;oBACjB,QAAQ,EAAE,CAAC;iBACZ;aACF;SACF,EAAE,MAAM,CAAC,CAAC;QAEX,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC;YACnC,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,MAAM;YACjB,YAAY,EAAE,CAAC,MAAM,CAAC;YACtB,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;QAC7D,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;QACtE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC;YAChC,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;SACpB,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,6CAA6C,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/loop/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Configurable agentic loops — config model (declarative surface).
+ *
+ * An agent has a collection of named loops (one active at a time) and an
+ * optional pipeline: a tree of heterogeneous steps with deterministic
+ * conditions over a shared, read-only context bag. Step kinds: loop (LLM),
+ * switch (deterministic branch), parallel (fork-join), human (structured human
+ * decision). See the loop-architecture design.
+ */
+export interface Condition {
+    /** Expression over the context bag, evaluated by SafeExpressionEvaluator. */
+    expression: string;
+}
+export type ContextBag = Record<string, unknown>;
+export interface LoopConfig {
+    /** Optional — the loops-map key is the canonical name. */
+    name?: string;
+    systemPrompt?: string;
+    /** Tool subset active in this loop (restriction = determinism/safety). */
+    tools?: string[];
+    model?: string;
+    reasoning?: string;
+    temperature?: number;
+    maxTurns?: number;
+    /** Deterministic stop condition over the context bag. */
+    stopWhen?: Condition;
+    /** Structured output contract — the loop's typed deliverable. */
+    output?: {
+        schema?: unknown;
+    };
+}
+export interface SwitchCase {
+    when: string;
+    steps: Step[];
+}
+export type Step = {
+    loop: string;
+    when?: string;
+} | {
+    parallel: Step[];
+    join?: "all" | "any" | number;
+    when?: string;
+} | {
+    switch: {
+        cases: SwitchCase[];
+        default?: {
+            steps: Step[];
+        };
+    };
+    when?: string;
+} | {
+    human: string;
+    output?: {
+        schema?: unknown;
+    };
+    notify?: string[];
+    when?: string;
+};
+export interface Pipeline {
+    mode?: "sequential" | "parallel";
+    context?: "shared";
+    steps: Step[];
+}
+export interface AgentLoopConfig {
+    name?: string;
+    model?: string;
+    /** Out-of-scope runtime/environment ref (default polpo-runner; custom image later). */
+    runtime?: string;
+    loops: Record<string, LoopConfig>;
+    pipeline?: Pipeline;
+}
+export declare const isLoopStep: (s: Step) => s is {
+    loop: string;
+    when?: string;
+};
+export declare const isParallelStep: (s: Step) => s is {
+    parallel: Step[];
+    join?: "all" | "any" | number;
+    when?: string;
+};
+export declare const isSwitchStep: (s: Step) => s is {
+    switch: {
+        cases: SwitchCase[];
+        default?: {
+            steps: Step[];
+        };
+    };
+    when?: string;
+};
+export declare const isHumanStep: (s: Step) => s is {
+    human: string;
+    output?: {
+        schema?: unknown;
+    };
+    notify?: string[];
+    when?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/loop/types.d.ts.map

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

package/dist/loop/types.js

@@ -0,0 +1,15 @@
+/**
+ * Configurable agentic loops — config model (declarative surface).
+ *
+ * An agent has a collection of named loops (one active at a time) and an
+ * optional pipeline: a tree of heterogeneous steps with deterministic
+ * conditions over a shared, read-only context bag. Step kinds: loop (LLM),
+ * switch (deterministic branch), parallel (fork-join), human (structured human
+ * decision). See the loop-architecture design.
+ */
+// ─── Step type guards ────────────────────────────────────
+export const isLoopStep = (s) => "loop" in s;
+export const isParallelStep = (s) => "parallel" in s;
+export const isSwitchStep = (s) => "switch" in s;
+export const isHumanStep = (s) => "human" in s;
+//# sourceMappingURL=types.js.map

package/dist/loop/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/loop/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmDH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAO,EAAwC,EAAE,CAAC,MAAM,IAAI,CAAC,CAAC;AACzF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAO,EAA2E,EAAE,CACjH,UAAU,IAAI,CAAC,CAAC;AAClB,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,CAAO,EAC+E,EAAE,CAAC,QAAQ,IAAI,CAAC,CAAC;AACzG,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,CAAO,EACkF,EAAE,CAAC,OAAO,IAAI,CAAC,CAAC"}