@polpo-ai/core 0.15.40 → 0.15.42

package/README.md

@@ -188,6 +188,53 @@ deterministically. Timeout, provider failure, malformed output, unknown
 profiles, and low confidence use the configured fallback; caller cancellation
 stops planning instead of starting execution with a fallback.
 
+## Typed Memory
+
+Typed Memory is additive to the legacy markdown `MemoryStore`:
+
+```ts
+import {
+  createMemoryItem,
+  canAccessMemoryScope,
+} from "@polpo-ai/core/memory";
+
+const item = createMemoryItem({
+  scope: { kind: "user", subjectId: "external-user-123" },
+  kind: "preference",
+  content: "Prefers concise answers.",
+  provenance: { source: "explicit", actor: "user" },
+});
+```
+
+Scopes never default to global access. User scopes refer to the host
+application's external user, not a Polpo account member. The host owns its
+project or organization boundary and passes only authorized dimensions to
+`canAccessMemoryScope`.
+
+The contract validates item lifecycle, provenance, expiry, and exact dedupe
+identity. `InMemoryMemoryItemStore` adds authorized CRUD, deterministic lexical
+search, token-budget selection, soft deletion, usage events, and fail-closed
+write policy. Every operation requires a host-owned `namespace`, so external
+user identifiers are never shared across project boundaries.
+
+`FileMemoryItemStore` from `@polpo-ai/file-stores` is the local durable
+reference adapter. It writes `memory-items.json` atomically and leaves the
+existing markdown store untouched during migration.
+
+The typed HTTP and model-tool surfaces are separate opt-ins:
+
+- `memoryItemRoutes` in `@polpo-ai/server` receives a host-resolved
+  `MemoryStoreContext`, so authentication, namespace, and external-user
+  identity stay at the composition root.
+- `createTypedMemoryTools` in `@polpo-ai/tools` returns only explicitly granted
+  search, remember, update, or forget actions. Write scope and provenance are
+  fixed by the host rather than supplied by the model.
+- `PolpoClient` in `@polpo-ai/sdk` exposes typed list, create, search, update,
+  and forget methods.
+
+No typed Memory route or tool is mounted automatically, and this layer does not
+inject retrieved items into prompts. Runtime retrieval is a separate opt-in.
+
 ## License
 
 Apache 2.0

package/dist/__tests__/memory-store-policy.test.d.ts

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

package/dist/__tests__/memory-store-policy.test.d.ts.map

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

package/dist/__tests__/memory-store-policy.test.js

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import { InMemoryMemoryItemStore, MemoryConflictError, MemoryPolicyError, createMemoryItem, detectSensitiveMemoryContent, evaluateMemoryWrite, rankMemoryItems, selectMemoryResultsWithinBudget, } from "../memory/index.js";
+const context = {
+    namespace: "project-a",
+    access: {
+        projectId: "project-a",
+        agentName: "support",
+        externalUserId: "user-a",
+    },
+    surface: "api",
+};
+function item(id, content, scope = { kind: "agent", agentName: "support" }) {
+    return createMemoryItem({
+        id,
+        scope,
+        kind: "fact",
+        content,
+        provenance: { source: "explicit", actor: "user" },
+    }, {
+        now: () => "2026-07-28T10:00:00.000Z",
+    });
+}
+describe("Memory write policy", () => {
+    it.each([
+        ["-----BEGIN PRIVATE KEY-----\nabc\n-----END PRIVATE KEY-----", "private_key"],
+        ["Authorization: Bearer abcdefghijklmnopqrstuvwxyz", "bearer_token"],
+        ["api_key = 'abcdefghijklmnopqrstuvwxyz123456'", "credential_assignment"],
+        ["ghp_1234567890abcdefghijklmnopqrstuvwxyz", "known_token_prefix"],
+    ])("denies sensitive content without returning the matched secret", async (content, expectedCode) => {
+        const findings = detectSensitiveMemoryContent(content);
+        expect(findings.map((finding) => finding.code)).toContain(expectedCode);
+        expect(JSON.stringify(findings)).not.toContain(content);
+        const decision = await evaluateMemoryWrite(item("secret", content), context);
+        expect(decision.allowed).toBe(false);
+        expect(decision.violations.map((violation) => violation.code))
+            .toContain("sensitive_content");
+    });
+    it("does not reject ordinary security prose as a secret", async () => {
+        const content = "The password rotation policy runs every 90 days.";
+        expect(detectSensitiveMemoryContent(content)).toEqual([]);
+        await expect(evaluateMemoryWrite(item("safe", content), context))
+            .resolves.toMatchObject({ allowed: true });
+    });
+    it("scans optional summaries and does not persist a denied write", async () => {
+        const store = new InMemoryMemoryItemStore();
+        const unsafe = {
+            ...item("summary-secret", "Safe body."),
+            summary: "api_key=abcdefghijklmnopqrstuvwxyz123456",
+        };
+        await expect(store.create(unsafe, context)).rejects.toBeInstanceOf(MemoryPolicyError);
+        expect(await store.list({}, context)).toEqual([]);
+    });
+    it("denies broad-scope writes from public channels by default", async () => {
+        const publicChannel = {
+            ...context,
+            surface: "channel",
+            channelVisibility: "public",
+        };
+        const broad = item("broad", "Treat this as project truth.", { kind: "project", subjectId: "project-a" });
+        const userScoped = item("user", "Prefers short answers.", { kind: "user", subjectId: "user-a" });
+        await expect(evaluateMemoryWrite(broad, publicChannel))
+            .resolves.toMatchObject({ allowed: false });
+        await expect(evaluateMemoryWrite(userScoped, publicChannel))
+            .resolves.toMatchObject({ allowed: true });
+    });
+    it("runs a custom sensitive-content hook and fails closed when it errors", async () => {
+        const denied = await evaluateMemoryWrite(item("custom", "internal codename"), context, {
+            sensitiveContentHook: () => [{
+                    code: "custom_dlp",
+                    start: 0,
+                    length: 8,
+                }],
+        });
+        expect(denied.allowed).toBe(false);
+        const store = new InMemoryMemoryItemStore({
+            sensitiveContentHook: () => {
+                throw new Error("scanner offline");
+            },
+        });
+        await expect(store.create(item("failure", "safe value"), context))
+            .rejects.toBeInstanceOf(MemoryPolicyError);
+        expect(await store.list({}, context)).toEqual([]);
+    });
+    it("detects concurrent updates across an asynchronous policy boundary", async () => {
+        let releaseScan;
+        let blockScans = false;
+        const scanReleased = new Promise((resolve) => {
+            releaseScan = resolve;
+        });
+        const store = new InMemoryMemoryItemStore({
+            sensitiveContentHook: async () => {
+                if (blockScans)
+                    await scanReleased;
+                return [];
+            },
+        });
+        await store.create(item("race", "Initial value."), context);
+        blockScans = true;
+        const first = store.update("race", { content: "First writer." }, context);
+        const second = store.update("race", { content: "Second writer." }, context);
+        await Promise.resolve();
+        releaseScan?.();
+        const settled = await Promise.allSettled([first, second]);
+        expect(settled.filter((result) => result.status === "fulfilled")).toHaveLength(1);
+        const rejected = settled.find((result) => result.status === "rejected");
+        expect(rejected).toMatchObject({
+            status: "rejected",
+            reason: expect.any(MemoryConflictError),
+        });
+    });
+});
+describe("Memory lexical ranking", () => {
+    it("is deterministic, finite, and stable under ties", () => {
+        const items = [
+            item("b", "Billing invoice details."),
+            item("a", "Billing invoice details."),
+            item("c", "Unrelated content."),
+        ];
+        const ranked = rankMemoryItems(items, "billing invoice");
+        expect(ranked.map((result) => result.item.id)).toEqual(["a", "b"]);
+        expect(ranked.every((result) => Number.isFinite(result.score))).toBe(true);
+        expect(ranked.every((result) => result.matchedTerms.length > 0)).toBe(true);
+    });
+    it("never returns a selection above the token budget", () => {
+        const ranked = rankMemoryItems([
+            item("a", "alpha ".repeat(20)),
+            item("b", "alpha ".repeat(10)),
+            item("c", "alpha"),
+        ], "alpha");
+        const selected = selectMemoryResultsWithinBudget(ranked, {
+            tokenBudget: 12,
+            maxResults: 10,
+        });
+        expect(selected.reduce((total, result) => total + result.estimatedTokens, 0)).toBeLessThanOrEqual(12);
+        expect(selected.map((result) => result.item.id)).toEqual(["c"]);
+        expect(selectMemoryResultsWithinBudget(ranked, {
+            tokenBudget: 0,
+        })).toEqual([]);
+    });
+});
+//# sourceMappingURL=memory-store-policy.test.js.map

package/dist/__tests__/memory-store-policy.test.js.map

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

package/dist/__tests__/typed-memory.test.d.ts

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

package/dist/__tests__/typed-memory.test.d.ts.map

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

package/dist/__tests__/typed-memory.test.js

@@ -0,0 +1,226 @@
+import { describe, expect, it } from "vitest";
+import { MemoryContractError, assertMemoryStatusTransition, canAccessMemoryScope, createMemoryDedupeIdentity, createMemoryItem, isMemoryItemExpired, isMemoryItemRetrievable, memoryScopeKey, normalizeMemoryItem, normalizeMemoryScope, renderMemoryItemsMarkdown, } from "../memory/index.js";
+const fixedFactory = {
+    createId: () => "memory-1",
+    now: () => "2026-07-28T12:00:00.000Z",
+};
+function input(overrides = {}) {
+    return {
+        scope: { kind: "agent", agentName: "support" },
+        kind: "fact",
+        content: "The customer uses annual billing.",
+        provenance: {
+            source: "explicit",
+            actor: "user",
+            sourceId: "message-1",
+        },
+        ...overrides,
+    };
+}
+describe("typed Memory contracts", () => {
+    it("creates a validated immutable item with deterministic defaults", () => {
+        const item = createMemoryItem(input(), fixedFactory);
+        expect(item).toEqual({
+            id: "memory-1",
+            scope: { kind: "agent", agentName: "support" },
+            kind: "fact",
+            content: "The customer uses annual billing.",
+            provenance: {
+                source: "explicit",
+                actor: "user",
+                sourceId: "message-1",
+            },
+            status: "active",
+            createdAt: "2026-07-28T12:00:00.000Z",
+            updatedAt: "2026-07-28T12:00:00.000Z",
+        });
+        expect(Object.isFrozen(item)).toBe(true);
+        expect(Object.isFrozen(item.scope)).toBe(true);
+        expect(Object.isFrozen(item.provenance)).toBe(true);
+    });
+    it.each([
+        [{ kind: "org", subjectId: "org-1" }],
+        [{ kind: "project", subjectId: "project-1" }],
+        [{ kind: "agent", agentName: "support" }],
+        [{ kind: "user", subjectId: "external-user-1", agentName: "support" }],
+        [{ kind: "channel", subjectId: "telegram:123" }],
+        [{ kind: "session", subjectId: "session-1" }],
+    ])("normalizes valid scope %#", (scope) => {
+        expect(normalizeMemoryScope(scope)).toEqual(scope);
+    });
+    it.each([
+        undefined,
+        null,
+        {},
+        { kind: "org" },
+        { kind: "project", subjectId: "" },
+        { kind: "agent" },
+        { kind: "agent", agentName: "" },
+        { kind: "user" },
+        { kind: "channel", subjectId: " " },
+        { kind: "session" },
+        { kind: "global" },
+    ])("rejects ambiguous or malformed scope %#", (scope) => {
+        expect(() => normalizeMemoryScope(scope)).toThrow(MemoryContractError);
+    });
+    it("authorizes scopes only against the matching caller dimension", () => {
+        const access = {
+            orgId: "org-1",
+            projectId: "project-1",
+            agentName: "support",
+            externalUserId: "external-user-1",
+            channelId: "telegram:123",
+            sessionId: "session-1",
+        };
+        expect(canAccessMemoryScope({ kind: "org", subjectId: "org-1" }, access)).toBe(true);
+        expect(canAccessMemoryScope({ kind: "project", subjectId: "project-1" }, access)).toBe(true);
+        expect(canAccessMemoryScope({ kind: "agent", agentName: "support" }, access)).toBe(true);
+        expect(canAccessMemoryScope({
+            kind: "user",
+            subjectId: "external-user-1",
+            agentName: "support",
+        }, access)).toBe(true);
+        expect(canAccessMemoryScope({ kind: "channel", subjectId: "telegram:123" }, access)).toBe(true);
+        expect(canAccessMemoryScope({ kind: "session", subjectId: "session-1" }, access)).toBe(true);
+        expect(canAccessMemoryScope({
+            kind: "user",
+            subjectId: "external-user-1",
+            agentName: "sales",
+        }, access)).toBe(false);
+        expect(canAccessMemoryScope({
+            kind: "user",
+            subjectId: "external-user-1",
+        }, { projectId: "project-1" })).toBe(false);
+        expect(canAccessMemoryScope({
+            kind: "project",
+            subjectId: "project-2",
+        }, access)).toBe(false);
+    });
+    it("never treats an omitted external user as project-wide access", () => {
+        expect(canAccessMemoryScope({ kind: "user", subjectId: "same-user" }, { projectId: "project-a", agentName: "support" })).toBe(false);
+    });
+    it("creates stable, scope-aware exact dedupe identities", () => {
+        const first = createMemoryDedupeIdentity({
+            scope: { kind: "user", subjectId: "user-1", agentName: "support" },
+            kind: "preference",
+            content: "  Prefers   concise\u00a0answers. ",
+        });
+        const equivalent = createMemoryDedupeIdentity({
+            scope: { kind: "user", subjectId: "user-1", agentName: "support" },
+            kind: "preference",
+            content: "prefers concise answers.",
+        });
+        const otherUser = createMemoryDedupeIdentity({
+            scope: { kind: "user", subjectId: "user-2", agentName: "support" },
+            kind: "preference",
+            content: "prefers concise answers.",
+        });
+        expect(first).toBe(equivalent);
+        expect(first).not.toBe(otherUser);
+        expect(memoryScopeKey({
+            kind: "user",
+            subjectId: "user-1",
+            agentName: "support",
+        })).toBe('["user","user-1","support"]');
+    });
+    it.each([
+        ["pending", "active", true],
+        ["pending", "deleted", true],
+        ["active", "superseded", true],
+        ["active", "deleted", true],
+        ["superseded", "deleted", true],
+        ["active", "pending", false],
+        ["superseded", "active", false],
+        ["deleted", "active", false],
+    ])("enforces %s -> %s status transitions", (from, to, allowed) => {
+        if (allowed) {
+            expect(() => assertMemoryStatusTransition(from, to)).not.toThrow();
+        }
+        else {
+            expect(() => assertMemoryStatusTransition(from, to)).toThrow(MemoryContractError);
+        }
+    });
+    it("allows idempotent lifecycle writes", () => {
+        expect(() => assertMemoryStatusTransition("active", "active")).not.toThrow();
+        expect(() => assertMemoryStatusTransition("deleted", "deleted")).not.toThrow();
+    });
+    it("filters expired, pending, superseded, and deleted items from retrieval", () => {
+        const active = createMemoryItem(input({
+            expiresAt: "2026-07-28T13:00:00.000Z",
+        }), fixedFactory);
+        const expired = createMemoryItem(input({
+            expiresAt: "2026-07-28T11:59:59.999Z",
+        }), fixedFactory);
+        const pending = createMemoryItem(input({ status: "pending" }), fixedFactory);
+        expect(isMemoryItemExpired(active, fixedFactory.now())).toBe(false);
+        expect(isMemoryItemRetrievable(active, fixedFactory.now())).toBe(true);
+        expect(isMemoryItemExpired(expired, fixedFactory.now())).toBe(true);
+        expect(isMemoryItemRetrievable(expired, fixedFactory.now())).toBe(false);
+        expect(isMemoryItemRetrievable(pending, fixedFactory.now())).toBe(false);
+        expect(() => isMemoryItemExpired({ expiresAt: "not-a-date" }, fixedFactory.now())).toThrow(MemoryContractError);
+    });
+    it("normalizes persisted items and rejects malformed or future kinds safely", () => {
+        const item = createMemoryItem(input(), fixedFactory);
+        expect(normalizeMemoryItem(JSON.parse(JSON.stringify(item)))).toEqual(item);
+        for (const invalid of [
+            { ...item, kind: "unknown-future-kind" },
+            { ...item, confidence: Number.NaN },
+            { ...item, confidence: 1.1 },
+            { ...item, content: "" },
+            { ...item, createdAt: "not-a-date" },
+            { ...item, updatedAt: "2026-07-27T12:00:00.000Z" },
+            { ...item, provenance: { source: "run" } },
+        ]) {
+            expect(() => normalizeMemoryItem(invalid)).toThrow(MemoryContractError);
+        }
+    });
+    it("rejects empty and oversized content at the contract boundary", () => {
+        expect(() => createMemoryItem(input({ content: " " }), fixedFactory)).toThrow();
+        expect(() => createMemoryItem(input({ content: "x".repeat(32_001) }), fixedFactory)).toThrow();
+    });
+    it("renders a deterministic active-only markdown compatibility view", () => {
+        const first = createMemoryItem(input({
+            kind: "preference",
+            content: "Use concise answers.",
+        }), { createId: () => "b", now: () => "2026-07-28T11:00:00.000Z" });
+        const second = createMemoryItem(input({
+            kind: "fact",
+            content: "Annual billing is enabled.",
+        }), { createId: () => "a", now: () => "2026-07-28T10:00:00.000Z" });
+        const pending = createMemoryItem(input({
+            content: "Do not render me.",
+            status: "pending",
+        }), { createId: () => "c", now: () => "2026-07-28T09:00:00.000Z" });
+        expect(renderMemoryItemsMarkdown([first, pending, second])).toBe([
+            "- **Fact:** Annual billing is enabled.",
+            "- **Preference:** Use concise answers.",
+        ].join("\n"));
+    });
+    it("indents multiline content inside one compatibility list item", () => {
+        const item = createMemoryItem(input({
+            content: "First line\nSecond line",
+        }), fixedFactory);
+        expect(renderMemoryItemsMarkdown([item])).toBe("- **Fact:** First line\n  Second line");
+    });
+    it("copies caller-owned inputs instead of retaining mutable references", () => {
+        const scope = { kind: "agent", agentName: "support" };
+        const provenance = {
+            source: "explicit",
+            actor: "user",
+            sourceId: "message-1",
+        };
+        const item = createMemoryItem(input({ scope, provenance }), fixedFactory);
+        scope.agentName = "mutated";
+        provenance.sourceId = "mutated";
+        expect(item.scope).toEqual({ kind: "agent", agentName: "support" });
+        expect(item.provenance.sourceId).toBe("message-1");
+    });
+    it("renders no markdown block when there are no retrievable items", () => {
+        const deleted = {
+            ...createMemoryItem(input(), fixedFactory),
+            status: "deleted",
+        };
+        expect(renderMemoryItemsMarkdown([deleted])).toBe("");
+    });
+});
+//# sourceMappingURL=typed-memory.test.js.map

package/dist/__tests__/typed-memory.test.js.map

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

package/dist/adapter.d.ts

@@ -7,6 +7,7 @@ import type { LoopResumeState } from "@polpo-ai/core/loop-run-store";
 import type { ModelSelection } from "./model-policy.js";
 import type { RuntimePlan } from "./runtime-plan/index.js";
 import type { RuntimeSandboxOptions } from "./runtime-sandbox.js";
+import type { RuntimeContextResolution } from "./runtime-context/index.js";
 /**
  * Handle returned by the engine after spawning an agent.
  * The orchestrator uses this to monitor and control the agent.
@@ -46,6 +47,8 @@ export interface AgentHandle {
 export interface SpawnContext {
     /** Absolute path to the .polpo directory. Used for skill loading, logs, etc. */
     polpoDir: string;
+    /** Pre-resolved retrieval snapshot rendered into task system prompts. */
+    runtimeContext?: RuntimeContextResolution;
     /** Per-task output directory (.polpo/output/<taskId>/). Agents write deliverables here. */
     outputDir?: string;
     /** Email domain allowlist — restricts email_send tool to these domains. */

package/dist/adapter.d.ts.map

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

package/dist/execution-router.d.ts

@@ -1,4 +1,5 @@
 import type { ProjectLoopConfig } from "./loop/types.js";
+import type { AgentConfig, Task } from "./types.js";
 import { type RuntimeDecisionSource, type RuntimeInvocationSource, type RuntimeSurface } from "./runtime-plan/index.js";
 export declare const EXECUTION_ROUTER_MODES: readonly ["off", "auto"];
 export type ExecutionRouterMode = (typeof EXECUTION_ROUTER_MODES)[number];
@@ -93,6 +94,15 @@ export interface ResolveExecutionRouteOptions {
     readonly resolveClassifier?: () => ExecutionRouteClassifier | undefined | Promise<ExecutionRouteClassifier | undefined>;
     readonly signal?: AbortSignal;
 }
+export interface ResolveTaskExecutionRouteInput {
+    readonly task: Pick<Task, "description" | "loop" | "title" | "user">;
+    readonly agent: AgentConfig;
+}
+export interface ResolveTaskExecutionRouteOptions {
+    readonly getProjectLoop?: (name: string) => ProjectLoopConfig | null | Promise<ProjectLoopConfig | null>;
+    readonly resolveClassifier?: (context: ExecutionRouteClassifierResolverContext) => ExecutionRouteClassifier | undefined | Promise<ExecutionRouteClassifier | undefined>;
+    readonly signal?: AbortSignal;
+}
 export interface CreateExplicitExecutionRouteInput {
     readonly surface: RuntimeSurface;
     readonly source: RuntimeInvocationSource;
@@ -139,6 +149,12 @@ export declare class ExecutionRouteCancelledError extends Error {
  * before a request or task starts.
  */
 export declare function validateExecutionRouterConfig(config: ExecutionRouterConfig): void;
+/**
+ * Resolve routing for task execution independently of the host transport.
+ * Orchestrators and direct task APIs share this helper so task semantics cannot
+ * diverge between background and request-driven execution.
+ */
+export declare function resolveTaskExecutionRoute(input: ResolveTaskExecutionRouteInput, options?: ResolveTaskExecutionRouteOptions): Promise<ResolvedExecutionRoute | undefined>;
 export declare function compileExecutionRouteManifest(input: CompileExecutionRouteManifestInput): ExecutionRouteManifest;
 export declare function resolveExecutionRoute(input: ResolveExecutionRouteInput, options?: ResolveExecutionRouteOptions): Promise<ResolvedExecutionRoute>;
 export declare function createExplicitExecutionRoute(input: CreateExplicitExecutionRouteInput): ResolvedExecutionRoute;

package/dist/execution-router.d.ts.map

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

package/dist/execution-router.js

@@ -1,3 +1,4 @@
+import { resolveLoopSelection } from "./loop/selector.js";
 import { RUNTIME_INVOCATION_SOURCES, RUNTIME_SURFACES, } from "./runtime-plan/index.js";
 export const EXECUTION_ROUTER_MODES = ["off", "auto"];
 export const DEFAULT_EXECUTION_ROUTE_MIN_CONFIDENCE = 0.7;
@@ -148,6 +149,59 @@ function normalizeConfig(config) {
 export function validateExecutionRouterConfig(config) {
     normalizeConfig(config);
 }
+/**
+ * Resolve routing for task execution independently of the host transport.
+ * Orchestrators and direct task APIs share this helper so task semantics cannot
+ * diverge between background and request-driven execution.
+ */
+export async function resolveTaskExecutionRoute(input, options = {}) {
+    const { task, agent } = input;
+    if (task.loop) {
+        resolveLoopSelection(agent, task.loop);
+        return createExplicitExecutionRoute({
+            surface: "task",
+            source: "task",
+            loop: task.loop,
+        });
+    }
+    if (agent.executionRouter?.mode !== "auto")
+        return undefined;
+    validateExecutionRouterConfig(agent.executionRouter);
+    const assignedLoops = Array.isArray(agent.assignedLoops)
+        ? agent.assignedLoops
+        : [];
+    const configuredAllowedLoops = Array.isArray(agent.executionRouter.allowedLoops)
+        ? agent.executionRouter.allowedLoops
+        : [];
+    const allowed = new Set(configuredAllowedLoops);
+    const candidateNames = [...new Set(assignedLoops.filter((name) => allowed.has(name)))];
+    const projectLoops = [];
+    if (options.getProjectLoop) {
+        const loaded = await Promise.all(candidateNames.map((name) => options.getProjectLoop(name)));
+        projectLoops.push(...loaded.filter((loop) => loop !== null));
+    }
+    return resolveExecutionRoute({
+        surface: "task",
+        source: "task",
+        input: [task.title, task.description].filter(Boolean).join("\n\n"),
+        labels: [],
+        manifest: compileExecutionRouteManifest({
+            assignedLoops: candidateNames,
+            projectLoops,
+        }),
+        config: agent.executionRouter,
+    }, {
+        resolveClassifier: options.resolveClassifier
+            ? () => options.resolveClassifier({
+                surface: "task",
+                source: "task",
+                agentName: agent.name,
+                ...(task.user ? { userId: task.user } : {}),
+            })
+            : undefined,
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+}
 function normalizeManifest(manifest) {
     const record = plainRecord(manifest, "Execution route manifest");
     if (record.version !== 1) {