agentenkit 0.1.0

package/dist/core/admin.js

@@ -0,0 +1,147 @@
+const EMPTY = {
+    inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, totalTokens: 0,
+};
+function percentiles(values) {
+    if (values.length === 0)
+        return null;
+    const s = [...values].sort((a, b) => a - b);
+    const at = (q) => s[Math.min(s.length - 1, Math.floor(q * s.length))];
+    return { p50: at(0.5), p95: at(0.95), max: s[s.length - 1] };
+}
+export function summarise(runs) {
+    const byState = {};
+    const byStopReason = {};
+    const tokens = { ...EMPTY };
+    const durations = [];
+    const queued = [];
+    let failed = 0;
+    for (const r of runs) {
+        byState[r.state] = (byState[r.state] ?? 0) + 1;
+        if (r.stopReason)
+            byStopReason[r.stopReason] = (byStopReason[r.stopReason] ?? 0) + 1;
+        tokens.inputTokens += r.inputTokens;
+        tokens.cachedInputTokens += r.cachedInputTokens;
+        tokens.outputTokens += r.outputTokens;
+        tokens.totalTokens += r.totalTokens;
+        if (typeof r.durationMs === 'number')
+            durations.push(r.durationMs);
+        if (typeof r.queuedMs === 'number')
+            queued.push(r.queuedMs);
+        if (r.state === 'FAILED')
+            failed += 1;
+    }
+    return {
+        total: runs.length,
+        byState,
+        byStopReason,
+        tokens,
+        duration: percentiles(durations),
+        queued: percentiles(queued),
+        failed,
+    };
+}
+/** Default window for a dashboard read: enough to be useful, bounded enough
+ *  that "show me everything" can never become a table scan. */
+const DEFAULT_LIMIT = 200;
+export async function listRuns(deps, filter = {}) {
+    return deps.admin.runs.list({ ...filter, limit: filter.limit ?? DEFAULT_LIMIT });
+}
+export async function runStats(deps, range = {}) {
+    // Percentiles are computed here rather than pushed into the adapter, so an
+    // adapter only ever writes filters it can express in one indexed query.
+    return summarise(await listRuns(deps, { ...range, limit: range.limit ?? 1_000 }));
+}
+export async function overview(deps, range = {}) {
+    const [threads, runsByState, recent, active] = await Promise.all([
+        deps.admin.threads.countByState(),
+        deps.admin.runs.countByState(),
+        listRuns(deps, { since: range.since, limit: 1_000 }),
+        deps.admin.runs.list({ state: ['RUNNING', 'WAITING_FOR_INPUT'], limit: 50 }),
+    ]);
+    return { runs: summarise(recent), threads, runsByState, active };
+}
+/** A run's steps, in order (§2.9). Rows in the platform's own store rather
+ *  than a scan of the caller's event log. */
+export async function listSteps(deps, runId) {
+    return deps.admin.steps.listByRun(runId);
+}
+const addTokens = (into, from) => {
+    into.inputTokens += from.inputTokens;
+    into.cachedInputTokens += from.cachedInputTokens;
+    into.outputTokens += from.outputTokens;
+    into.totalTokens += from.totalTokens;
+};
+function rollUp(thread, runs) {
+    const tokens = { ...EMPTY };
+    let steps = 0;
+    let durationMs = 0;
+    for (const r of runs) {
+        addTokens(tokens, r);
+        steps += r.steps;
+        durationMs += r.durationMs ?? 0;
+    }
+    // The dispatched run is the one a person started; a nested run's prompt is
+    // a brief the model wrote.
+    const root = runs.filter((r) => r.depth === 0).sort((a, b) => a.startedAt.getTime() - b.startedAt.getTime())[0];
+    return { ...thread, runs: runs.length, steps, tokens, durationMs, prompt: root?.prompt ?? null };
+}
+/** Threads with their runs rolled up, newest activity first (§2.9). One pass
+ *  over the window's runs rather than a query per thread. */
+export async function listThreads(deps, filter = {}) {
+    const [threads, runs] = await Promise.all([
+        deps.admin.threads.list({ ...filter, limit: filter.limit ?? DEFAULT_LIMIT }),
+        deps.admin.runs.list({ since: filter.since, limit: 5_000 }),
+    ]);
+    const byThread = new Map();
+    for (const r of runs) {
+        const list = byThread.get(r.threadId) ?? [];
+        list.push(r);
+        byThread.set(r.threadId, list);
+    }
+    return threads.map((t) => rollUp(t, byThread.get(t.id) ?? []));
+}
+/** One thread opened up: its runs and every step across them (§2.9). */
+export async function getThread(deps, threadId) {
+    const [runs, steps] = await Promise.all([
+        deps.admin.runs.listByThread(threadId),
+        deps.admin.steps.listByThread(threadId),
+    ]);
+    const rows = await deps.admin.threads.list({ limit: 5_000 });
+    const thread = rows.find((t) => t.id === threadId);
+    if (!thread && runs.length === 0)
+        return null;
+    const base = thread ?? {
+        id: threadId,
+        state: (runs[0]?.state ?? 'IDLE'),
+        model: runs[0]?.model ?? 'unknown',
+        firstSeenAt: runs.at(-1)?.startedAt ?? new Date(),
+        updatedAt: runs[0]?.startedAt ?? new Date(),
+    };
+    return { thread: rollUp(base, runs), runs, steps };
+}
+export async function getRun(deps, runId) {
+    const run = await deps.admin.runs.get(runId);
+    if (!run)
+        return null;
+    const [steps, siblings, events] = await Promise.all([
+        listSteps(deps, runId),
+        deps.admin.runs.listByThread(run.threadId),
+        deps.storage.events.listSince(run.threadId, -1),
+    ]);
+    const from = new Date(run.startedAt).getTime();
+    const to = run.endedAt ? new Date(run.endedAt).getTime() : Infinity;
+    return {
+        run,
+        steps,
+        // Its children: same table, distinguished by depth (§2.7).
+        subagents: siblings.filter((c) => c.parentRunId === runId),
+        // CHUNK is the token firehose; a timeline wants the spine.
+        events: events.filter((e) => {
+            if (e.type === 'CHUNK' || e.type === 'SUBAGENT_CHUNK')
+                return false;
+            const at = new Date(e.createdAt).getTime();
+            return at >= from && at <= to;
+        }),
+    };
+}
+//# sourceMappingURL=admin.js.map

package/dist/core/admin.js.map

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

package/dist/core/agent.d.ts

@@ -0,0 +1,29 @@
+import type { RuntimePorts } from '../ports/runtime.js';
+import type { AgentRunState } from './state.js';
+import type { AgentHandle, AgentKind, GenerateTextAgentSpec, ProviderOptions, StreamTextAgentSpec, SubagentsConfig } from '../ports/runtime.js';
+import { Semaphore } from './subagent.js';
+/** The registry entry behind a handle: the bound generation flavor, the
+ *  spec-level defaults the engine reads, and the user's generation args
+ *  (spread first, platform keys last — §3.1). */
+export interface RegisteredAgent {
+    name: string;
+    kind: AgentKind;
+    spec: {
+        model?: string;
+        subagents?: boolean | SubagentsConfig;
+        tokenBudget?: number;
+        /** Additional provider-specific options (§3.1) — merged per run. */
+        providerOptions?: ProviderOptions;
+    };
+    /** The user's generation args — spread first, platform keys last (§3.1). */
+    args: Record<string, any>;
+    sem: Semaphore;
+}
+/** Normalize the delegation config: `false`/`undefined` = off; `true` = defaults. */
+export declare function normalizeSubagents(spec: boolean | SubagentsConfig | undefined): SubagentsConfig | null;
+/** Resolves the ports for one call, binding that call's state to storage
+ *  (§2.10). A handle outlives many runs, so it cannot hold fixed ports. */
+export type ScopeFn = (state?: AgentRunState, runId?: string) => RuntimePorts;
+export declare function createStreamTextAgent(scope: ScopeFn, spec: StreamTextAgentSpec): AgentHandle;
+export declare function createGenerateTextAgent(scope: ScopeFn, spec: GenerateTextAgentSpec): AgentHandle;
+//# sourceMappingURL=agent.d.ts.map

package/dist/core/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,qBAAqB,EACrB,eAAe,EAEf,mBAAmB,EACnB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI1C;;iDAEiD;AACjD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;QACtC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,oEAAoE;QACpE,eAAe,CAAC,EAAE,eAAe,CAAC;KACnC,CAAC;IACF,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,qFAAqF;AACrF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,GAC1C,eAAe,GAAG,IAAI,CAGxB;AAED;2EAC2E;AAC3E,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,YAAY,CAAC;AAc9E,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,mBAAmB,GACxB,WAAW,CASb;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,qBAAqB,GAC1B,WAAW,CASb"}

package/dist/core/agent.js

@@ -0,0 +1,41 @@
+import { execute, executeWithPolicy } from './engine.js';
+import { Semaphore } from './subagent.js';
+import { run } from './run.js';
+import { stop } from './stop.js';
+/** Normalize the delegation config: `false`/`undefined` = off; `true` = defaults. */
+export function normalizeSubagents(spec) {
+    if (!spec)
+        return null;
+    return spec === true ? {} : spec;
+}
+function createHandle(scope, agent) {
+    return {
+        name: agent.name,
+        kind: agent.kind,
+        execute: (input) => execute(scope(input.state, input.runId), agent, input),
+        executeWithPolicy: (input, policy) => executeWithPolicy(scope(input.state, input.runId), agent, input, policy),
+        run: (input) => run(scope(input.state), agent, input),
+        stop: (threadId, state) => stop(scope(state), threadId),
+    };
+}
+export function createStreamTextAgent(scope, spec) {
+    const { name, model, subagents, tokenBudget, providerOptions, ...args } = spec;
+    return createHandle(scope, {
+        name,
+        kind: 'stream-text',
+        spec: { model, subagents, tokenBudget, providerOptions },
+        args: args,
+        sem: new Semaphore(scope().config.subagentMaxConcurrent),
+    });
+}
+export function createGenerateTextAgent(scope, spec) {
+    const { name, model, subagents, tokenBudget, providerOptions, ...args } = spec;
+    return createHandle(scope, {
+        name,
+        kind: 'generate-text',
+        spec: { model, subagents, tokenBudget, providerOptions },
+        args: args,
+        sem: new Semaphore(scope().config.subagentMaxConcurrent),
+    });
+}
+//# sourceMappingURL=agent.js.map

package/dist/core/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAoBjC,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CAChC,IAA2C;IAE3C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACnC,CAAC;AAMD,SAAS,YAAY,CAAC,KAAc,EAAE,KAAsB;IAC1D,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,CAAC,KAAmB,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC;QACxF,iBAAiB,EAAE,CAAC,KAAmB,EAAE,MAAiC,EAAE,EAAE,CAC5E,iBAAiB,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC;QAC1E,GAAG,EAAE,CAAC,KAAe,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC;QAC/D,IAAI,EAAE,CAAC,QAAgB,EAAE,KAAqB,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;KAChF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,KAAc,EACd,IAAyB;IAEzB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC/E,OAAO,YAAY,CAAC,KAAK,EAAE;QACzB,IAAI;QACJ,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE;QACxD,IAAI,EAAE,IAA2B;QACjC,GAAG,EAAE,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC;KACzD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,KAAc,EACd,IAA2B;IAE3B,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC/E,OAAO,YAAY,CAAC,KAAK,EAAE;QACzB,IAAI;QACJ,IAAI,EAAE,eAAe;QACrB,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE;QACxD,IAAI,EAAE,IAA2B;QACjC,GAAG,EAAE,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC;KACzD,CAAC,CAAC;AACL,CAAC"}

package/dist/core/cache.d.ts

@@ -0,0 +1,37 @@
+/** Prompt caching (§2.6): providers like Anthropic cache a prompt prefix only
+ *  when it carries explicit cache breakpoints; OpenAI-family models cache
+ *  automatically for prompts ≥1024 tokens and ignore these markers.
+ *
+ *  `markPromptCaching` stamps ephemeral cache breakpoints on the stable
+ *  prefix of a prompt — the system message and the tail message of the
+ *  conversation-so-far — so the next run with the same prefix is served from
+ *  the provider cache (tracked as cachedInputTokens, §4 usage attribution).
+ *
+ *  The stamp uses the AI SDK's provider-metadata channel; unknown providers
+ *  ignore it harmlessly. */
+export interface PromptCachingOptions {
+    /** Provider namespace for the metadata stamp. Default: 'anthropic'. */
+    provider?: string;
+}
+interface CacheableMessage {
+    role: string;
+    content: unknown;
+    [key: string]: unknown;
+}
+/** A system prompt, in the one shape that can carry a cache breakpoint.
+ *
+ *  The SDK's `system:` STRING parameter becomes `{ role, content }` with no
+ *  metadata channel at all, so a system prompt passed that way can never be
+ *  cached — and it is usually the largest, most stable part of the prompt, the
+ *  very thing caching exists for. Carried as a message it can be stamped. */
+export declare function systemCacheMessage(system: string, provider?: string): {
+    role: 'system';
+    content: string;
+} & Record<string, unknown>;
+/** Mark the stable prefix of a prompt for provider-side caching:
+ *  the system message (if any) plus the last message of the history. */
+export declare function markPromptCaching<T extends CacheableMessage>(messages: T[], opts?: {
+    provider?: string;
+}): T[];
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/core/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/core/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;4BAU4B;AAC5B,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAQD,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AA0CD;;;;;6EAK6E;AAC7E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,SAAc,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAO/D;AAED;wEACwE;AACxE,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,gBAAgB,EAC1D,QAAQ,EAAE,CAAC,EAAE,EACb,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,CAAC,EAAE,CAaL"}

package/dist/core/cache.js

@@ -0,0 +1,68 @@
+const cacheStamp = (provider) => ({
+    [provider]: { cacheControl: { type: 'ephemeral' } },
+});
+function toParts(content) {
+    if (typeof content === 'string')
+        return [{ type: 'text', text: content }];
+    if (Array.isArray(content))
+        return content;
+    return [];
+}
+/** Stamp the marker where the SDK will actually read it.
+ *
+ *  Two rules, and breaking either one is silent:
+ *   - The SDK reads `providerOptions ?? experimental_providerMetadata`. A bare
+ *     `providerMetadata` is read by nothing, so stamping that alone leaves the
+ *     breakpoint inert — set, and never seen by a provider.
+ *   - A SYSTEM message's content must stay a string; it carries its metadata on
+ *     the message itself. Splitting it into parts the way a user message allows
+ *     makes the whole prompt fail validation, and every run throws. */
+function stampCacheBreakpoint(message, provider) {
+    if (message.role === 'system') {
+        return {
+            ...message,
+            providerOptions: cacheStamp(provider),
+            experimental_providerMetadata: cacheStamp(provider),
+        };
+    }
+    const parts = toParts(message.content);
+    if (parts.length === 0)
+        return message;
+    const stamped = [...parts];
+    const last = stamped[stamped.length - 1];
+    stamped[stamped.length - 1] = {
+        ...last,
+        providerOptions: cacheStamp(provider),
+        experimental_providerMetadata: cacheStamp(provider),
+    };
+    return { ...message, content: stamped };
+}
+/** A system prompt, in the one shape that can carry a cache breakpoint.
+ *
+ *  The SDK's `system:` STRING parameter becomes `{ role, content }` with no
+ *  metadata channel at all, so a system prompt passed that way can never be
+ *  cached — and it is usually the largest, most stable part of the prompt, the
+ *  very thing caching exists for. Carried as a message it can be stamped. */
+export function systemCacheMessage(system, provider = 'anthropic') {
+    return {
+        role: 'system',
+        content: system,
+        providerOptions: cacheStamp(provider),
+        experimental_providerMetadata: cacheStamp(provider),
+    };
+}
+/** Mark the stable prefix of a prompt for provider-side caching:
+ *  the system message (if any) plus the last message of the history. */
+export function markPromptCaching(messages, opts = {}) {
+    const provider = opts.provider ?? 'anthropic';
+    const out = messages.map((m) => ({ ...m }));
+    const systemIndex = out.findIndex((m) => m.role === 'system');
+    if (systemIndex >= 0)
+        out[systemIndex] = stampCacheBreakpoint(out[systemIndex], provider);
+    if (out.length > 0) {
+        const last = out.length - 1;
+        out[last] = stampCacheBreakpoint(out[last], provider);
+    }
+    return out;
+}
+//# sourceMappingURL=cache.js.map

package/dist/core/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/core/cache.ts"],"names":[],"mappings":"AA4BA,MAAM,UAAU,GAAG,CAAC,QAAgB,EAAE,EAAE,CAAC,CAAC;IACxC,CAAC,QAAQ,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE;CACpD,CAAC,CAAC;AAEH,SAAS,OAAO,CAAC,OAAgB;IAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC1E,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,OAA0B,CAAC;IAC9D,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;uEAQuE;AACvE,SAAS,oBAAoB,CAA6B,OAAU,EAAE,QAAgB;IACpF,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO;YACL,GAAG,OAAO;YACV,eAAe,EAAE,UAAU,CAAC,QAAQ,CAAC;YACrC,6BAA6B,EAAE,UAAU,CAAC,QAAQ,CAAC;SACpD,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACvC,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IAC1C,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG;QAC5B,GAAG,IAAI;QACP,eAAe,EAAE,UAAU,CAAC,QAAQ,CAAC;QACrC,6BAA6B,EAAE,UAAU,CAAC,QAAQ,CAAC;KACpD,CAAC;IACF,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;6EAK6E;AAC7E,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,QAAQ,GAAG,WAAW;IAEtB,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,MAAM;QACf,eAAe,EAAE,UAAU,CAAC,QAAQ,CAAC;QACrC,6BAA6B,EAAE,UAAU,CAAC,QAAQ,CAAC;KACpD,CAAC;AACJ,CAAC;AAED;wEACwE;AACxE,MAAM,UAAU,iBAAiB,CAC/B,QAAa,EACb,OAA8B,EAAE;IAEhC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,WAAW,CAAC;IAC9C,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5C,MAAM,WAAW,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC9D,IAAI,WAAW,IAAI,CAAC;QAAE,GAAG,CAAC,WAAW,CAAC,GAAG,oBAAoB,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;IAE1F,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QAC5B,GAAG,CAAC,IAAI,CAAC,GAAG,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/core/context.d.ts

@@ -0,0 +1,13 @@
+import type { RuntimePorts } from '../ports/runtime.js';
+import type { ContextUsage, MessageDTO } from './types.js';
+/** Universal context ceiling across all models (§2.6) */
+export declare const CONTEXT_TOKEN_CEILING = 265000;
+/** Effective budget = min(native window, ceiling). The model's declared
+ *  `contextWindow` (via `resolveModel`, §3.3) wins over the fallback tables;
+ *  models below the ceiling keep their native window. */
+export declare function contextBudget(deps: RuntimePorts, model: string): number;
+/** Read-only view of the §2.6 budget math — what compactContext would see on
+ *  the next run, without summarizing anything. */
+export declare function contextUsage(deps: RuntimePorts, threadId: string, model: string): Promise<ContextUsage>;
+export declare function compactContext(deps: RuntimePorts, threadId: string, model: string): Promise<MessageDTO[]>;
+//# sourceMappingURL=context.d.ts.map

package/dist/core/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI3D,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,SAAU,CAAC;AAS7C;;yDAEyD;AACzD,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAavE;AAID;kDACkD;AAClD,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,CAUvB;AAKD,wBAAsB,cAAc,CAClC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,UAAU,EAAE,CAAC,CA+CvB"}

package/dist/core/context.js

@@ -0,0 +1,87 @@
+import { generateText } from 'ai';
+import { publish } from './publish.js';
+import { attributeTokens } from './usage.js';
+/** Universal context ceiling across all models (§2.6) */
+export const CONTEXT_TOKEN_CEILING = 265_000;
+const DEFAULT_NATIVE_WINDOWS = {
+    'gpt-4o': 128_000,
+    'gpt-4o-mini': 128_000,
+    'claude-3-5-sonnet': 200_000,
+    'gemini-1.5-pro': 1_000_000,
+};
+/** Effective budget = min(native window, ceiling). The model's declared
+ *  `contextWindow` (via `resolveModel`, §3.3) wins over the fallback tables;
+ *  models below the ceiling keep their native window. */
+export function contextBudget(deps, model) {
+    let declared;
+    try {
+        declared = deps.resolveModel(model).contextWindow;
+    }
+    catch {
+        // unknown registry key — fall through to the tables below
+    }
+    const native = declared ??
+        deps.config.nativeWindows?.[model] ??
+        DEFAULT_NATIVE_WINDOWS[model] ??
+        deps.config.contextCeilingTokens;
+    return Math.min(native, deps.config.contextCeilingTokens);
+}
+const estimateTokens = (content) => Math.ceil(JSON.stringify(content).length / 4);
+/** Read-only view of the §2.6 budget math — what compactContext would see on
+ *  the next run, without summarizing anything. */
+export async function contextUsage(deps, threadId, model) {
+    const budgetTokens = contextBudget(deps, model) - deps.config.contextOutputReserveTokens;
+    // The main agent's stream only — a nested run's turns are its own (§2.7)
+    const history = await deps.storage.messages.list(threadId, { agentId: null });
+    return {
+        usedTokens: history.reduce((sum, m) => sum + estimateTokens(m.content), 0),
+        budgetTokens,
+        compactAtTokens: Math.floor(budgetTokens * deps.config.compactionTrigger),
+        messages: history.length,
+    };
+}
+// Returns a history array guaranteed to fit the model's budget. Compaction is
+// durable: the summary is persisted as a Message, so every client and every
+// reconnect replay (§2.2) reconstructs the exact same context.
+export async function compactContext(deps, threadId, model) {
+    const budget = contextBudget(deps, model) - deps.config.contextOutputReserveTokens;
+    // Scoped to the main agent: unscoped, delegated turns would be compacted
+    // into — and then fed back through — the parent's prompt (§2.7)
+    const history = await deps.storage.messages.list(threadId, { agentId: null });
+    const total = history.reduce((sum, m) => sum + estimateTokens(m.content), 0);
+    if (total <= budget * deps.config.compactionTrigger)
+        return history;
+    // Keep the most recent tail verbatim ...
+    const tail = [];
+    let tailTokens = 0;
+    for (const m of [...history].reverse()) {
+        if (tailTokens + estimateTokens(m.content) > budget * deps.config.contextTailShare)
+            break;
+        tail.unshift(m);
+        tailTokens += estimateTokens(m.content);
+    }
+    const older = history.slice(0, history.length - tail.length);
+    if (older.length === 0)
+        return history; // single oversized turn — blocked by the input guards above
+    // ... and summarize everything before it with a cheap model
+    const { text, usage, ...rest } = await generateText({
+        model: deps.resolveModel('gpt-4o-mini').instance(),
+        prompt: 'Summarize the following conversation history into a dense context brief ' +
+            '(decisions, open threads, key facts) for an AI agent:\n\n' +
+            older.map((m) => `${m.role}: ${JSON.stringify(m.content)}`).join('\n'),
+    });
+    const summary = await deps.storage.messages.append(threadId, {
+        role: 'system',
+        content: { type: 'CONTEXT_SUMMARY', text },
+    });
+    // Token attribution (§4): input + cached + output. The cache hit is reported
+    // in provider metadata, never in `usage` — attributing without it books every
+    // cached prompt at the full input price.
+    await deps.storage.usage.record(threadId, {
+        agentId: null,
+        ...attributeTokens(usage, rest.providerMetadata ?? rest.experimental_providerMetadata),
+    });
+    await publish(deps, threadId, 'CONTEXT_COMPACTED', { summarizedMessages: older.length });
+    return [summary, ...tail];
+}
+//# sourceMappingURL=context.js.map

package/dist/core/context.js.map

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

package/dist/core/deleteThread.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimePorts } from '../ports/runtime.js';
+import type { DeleteThreadResult } from '../ports/runtime.js';
+/** The §3.2 deletion behavior: one call removes the thread and everything
+ *  that follows it — messages, events, usage rows, subagent runs — plus the
+ *  thread's hot kv keys (state cache, run lock, event seq, retry counter).
+ *
+ *  Guards:
+ *  - RUNNING is refused: a live worker is mid-segment and would keep writing
+ *    behind the delete. `stop()` first, then delete.
+ *  - WAITING_FOR_INPUT deletes cleanly: a park holds NO process (§2.5) — the
+ *    run segment already ended, and a late resume dispatch is a no-op against
+ *    the missing thread (the engine's terminal-state guard, §2.8). */
+export declare function deleteThread(deps: RuntimePorts, threadId: string): Promise<DeleteThreadResult>;
+//# sourceMappingURL=deleteThread.d.ts.map

package/dist/core/deleteThread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleteThread.d.ts","sourceRoot":"","sources":["../../src/core/deleteThread.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAI9D;;;;;;;;;sEASsE;AACtE,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC,CAuB7B"}

package/dist/core/deleteThread.js

@@ -0,0 +1,34 @@
+import { publishNotice } from './publish.js';
+import { redriveKey, runIdKey } from './keys.js';
+/** The §3.2 deletion behavior: one call removes the thread and everything
+ *  that follows it — messages, events, usage rows, subagent runs — plus the
+ *  thread's hot kv keys (state cache, run lock, event seq, retry counter).
+ *
+ *  Guards:
+ *  - RUNNING is refused: a live worker is mid-segment and would keep writing
+ *    behind the delete. `stop()` first, then delete.
+ *  - WAITING_FOR_INPUT deletes cleanly: a park holds NO process (§2.5) — the
+ *    run segment already ended, and a late resume dispatch is a no-op against
+ *    the missing thread (the engine's terminal-state guard, §2.8). */
+export async function deleteThread(deps, threadId) {
+    const thread = await deps.storage.threads.get(threadId);
+    if (!thread)
+        return { accepted: false, error: 'Thread not found' };
+    if (thread.state === 'RUNNING') {
+        return { accepted: false, error: 'Thread has an active run — stop it before deleting' };
+    }
+    // Cascade: messages, events, usage, runs follow the thread (§3.2)
+    await deps.storage.threads.delete(threadId);
+    // Live UIs subscribed to the thread channel learn it ceased to exist —
+    // bus-only notice (seq 0, never persisted: the event log is gone with it)
+    await publishNotice(deps, threadId, 'THREAD_DELETED', { threadId });
+    // Hot cache cleanup — a deleted thread must not resurrect from kv
+    await deps.kv.del(`agent:state:${threadId}`);
+    await deps.kv.del(`agent:lock:${threadId}`);
+    await deps.kv.del(`agent:seq:${threadId}`);
+    await deps.kv.del(`agent:attempts:${threadId}`);
+    await deps.kv.del(runIdKey(threadId));
+    await deps.kv.del(redriveKey(threadId));
+    return { accepted: true };
+}
+//# sourceMappingURL=deleteThread.js.map

package/dist/core/deleteThread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleteThread.js","sourceRoot":"","sources":["../../src/core/deleteThread.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEjD;;;;;;;;;sEASsE;AACtE,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAkB,EAClB,QAAgB;IAEhB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;IACnE,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,oDAAoD,EAAE,CAAC;IAC1F,CAAC;IAED,kEAAkE;IAClE,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE5C,uEAAuE;IACvE,0EAA0E;IAC1E,MAAM,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAEpE,kEAAkE;IAClE,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,eAAe,QAAQ,EAAE,CAAC,CAAC;IAC7C,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,cAAc,QAAQ,EAAE,CAAC,CAAC;IAC5C,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,aAAa,QAAQ,EAAE,CAAC,CAAC;IAC3C,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,kBAAkB,QAAQ,EAAE,CAAC,CAAC;IAChD,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;IAExC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC"}

package/dist/core/engine.d.ts

@@ -0,0 +1,79 @@
+import type { RuntimePorts } from '../ports/runtime.js';
+import type { ExecutionState, ProviderOptions } from './types.js';
+import type { TokenAttribution } from './usage.js';
+import type { RegisteredAgent } from './agent.js';
+import { type AgentRunState } from './state.js';
+export { countTokens } from './usage.js';
+export { executeStep, isParked, runLoop, type LoopInput, type LoopOutcome, type RunLedger, type StepResult } from './loop.js';
+/** The safety cap (§2.1) must be either absent (unbounded apart from
+ *  maxSteps) or a positive number — `0`/negative/NaN would silently disable
+ *  the cap and let a run spend without bound. */
+export declare function validateTokenBudget(value: number | undefined, label: string): void;
+/** Tools the engine treats as destructive: parked behind parkForApproval
+ *  (§2.5) instead of executing directly. Purely a marker — see withHitl. */
+export declare function markRequiresConfirmation<T extends object>(t: T): T;
+/** The engine (§2.1, §5.6). Worker-side only — runs are dispatched via the
+ *  queue (§2.8) and may outlive any HTTP response.
+ *
+ *  Execution is a platform-owned loop of single-round-trip steps
+ *  (`executeStep`, maxSteps: 1): after EVERY step the produced messages are
+ *  persisted, so a worker that dies mid-run resumes from the last step, and
+ *  every continuation decision — tool results ready, budget spent, step
+ *  ceiling, HITL park, user stop — is made here between steps, never inside
+ *  the SDK.
+ *
+ *  Concurrency: acquires the per-thread run lock (`agent:lock:{threadId}`,
+ *  SET NX + lease) before any work — two workers can never run one thread,
+ *  and a crashed worker's lock expires instead of blocking forever (§3.4).
+ *  Returns 'lock-conflict' when the lock is held, so callers can tell a
+ *  genuine no-op apart from a completed run. */
+export interface ExecuteInput {
+    threadId: string;
+    model: string;
+    /** This dispatch's run id (§2.1). A job without one keeps the old
+     *  behavior: no staleness check, and no redrive on a lock conflict. */
+    runId?: string;
+    /** Epoch ms at enqueue, for the queue-wait measurement (§2.9). */
+    enqueuedAt?: number;
+    /** The run's state (§2.10) — carried so a redrive keeps it. */
+    state?: AgentRunState;
+    tokenBudget?: number;
+    providerOptions?: ProviderOptions;
+}
+/** 'executed'      — this worker ran the segment (or it was a legitimate no-op).
+ *  'lock-conflict' — someone else holds the thread's run lock; nothing ran.
+ *  'stale'         — a NEWER run owns the thread; this job must do nothing. */
+export type ExecuteOutcome = 'executed' | 'lock-conflict' | 'stale';
+export declare function execute(deps: RuntimePorts, agent: RegisteredAgent, input: ExecuteInput): Promise<ExecuteOutcome>;
+export interface FinalizeInput {
+    state: ExecutionState;
+    stopReason: 'completed' | 'token_budget' | 'max_steps' | 'cancelled';
+    tokensUsed: number;
+    attribution: TokenAttribution;
+    /** generate-text flavor only: publish the final text as one TEXT_RESULT. */
+    oneShotText?: string;
+    /** The run this finalize speaks for (§2.1). State is written only while
+     *  that run is still the thread's current one. */
+    runId?: string;
+    /** Loop iterations this segment completed (§2.9). */
+    steps?: number;
+    /** Why it failed, when it did (§2.9). */
+    error?: string;
+}
+/** Finalize a finished run (§5.6): attribute the segment's total tokens
+ *  (input + cached + output, §4), then flip state on both homes and publish.
+ *  Message persistence already happened per step inside the loop — finalize
+ *  never touches messages.
+ *
+ *  A budget break is NOT a user stop: the run completes with stopReason
+ *  'token_budget' and the usage it actually spent. */
+export declare function finalize(deps: RuntimePorts, agent: RegisteredAgent, threadId: string, f: FinalizeInput): Promise<void>;
+/** §2.8 failure policy: transient errors redrive through the queue; exhausted
+ *  attempts finalize FAILED (hot cache + durable). A user stop is never
+ *  retried, and a successful run resets the attempt counter.
+ *
+ *  `exec` is an injection seam for tests (default: the real execute). */
+export declare function executeWithPolicy(deps: RuntimePorts, agent: RegisteredAgent, input: ExecuteInput, policy?: {
+    maxAttempts?: number;
+}, exec?: typeof execute): Promise<void>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/core/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAc,MAAM,YAAY,CAAC;AAE9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAUlD,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAI9H;;iDAEiD;AACjD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIlF;AAED;4EAC4E;AAC5E,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAElE;AAiND;;;;;;;;;;;;;;gDAcgD;AAChD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd;2EACuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;+EAE+E;AAC/E,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,eAAe,GAAG,OAAO,CAAC;AAEpE,wBAAsB,OAAO,CAC3B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,cAAc,CAAC,CAwNzB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,EAAE,WAAW,GAAG,cAAc,GAAG,WAAW,GAAG,WAAW,CAAC;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;sDACkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;sDAMsD;AACtD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,CAAC,EAAE,aAAa,GACf,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAyCD;;;;yEAIyE;AACzE,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,YAAY,EACnB,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EACjC,IAAI,GAAE,OAAO,OAAiB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA+Cf"}