@aid-framework/runtime 0.0.0 → 0.1.39

package/dist/agents/loop.d.ts

@@ -0,0 +1,145 @@
+import { ConcurrencyLimiter } from '../concurrency.js';
+import { Budget, type CostLedger } from '../cost.js';
+import { ModelGateway } from '../gateway.js';
+import { Principal } from '../policy.js';
+import type { Provider } from '../providers/base.js';
+import { type Tool } from '../tools.js';
+import { Message } from '../types.js';
+import { type GuardrailRecord } from './guardrails.js';
+import { type AgentDefinition, type RuntimeSpec } from './ir.js';
+import { type MemoryStore, ThreadMemory } from './memory.js';
+import { type AgentCheckpoint, type HumanDecision, RunResult, type RunStatus, type StepRecord } from './state.js';
+/**
+ * The native agent engine: one loop, three ways to leave it.
+ *
+ * The loop is a model call, its tool calls, the observations, repeat -- until the model
+ * answers without a tool call, until `maxSteps` is spent, until a budget is crossed, or
+ * until a human is needed. It consumes a `RuntimeSpec` (the IR seam in `agents/ir`) and
+ * calls models through `ModelGateway`, so fallback, cost accounting, and tracing behave
+ * exactly as they do for a pipeline step.
+ *
+ * Two control edges, and the difference is not cosmetic:
+ *
+ * **transfer** -- IR `handoffs`. Control *moves*. The caller does not resume; the target
+ * owns the rest of the turn and its answer is the run's answer. The target inherits the
+ * conversation but not the caller's instructions: a system prompt belongs to an agent, not
+ * to a transcript. The runtime primitive is `transfer`, and it never returns to the caller.
+ *
+ * **delegate** -- IR `delegates` (Deep Agents `subagents`). Control is *lent*. The delegate
+ * gets an isolated context -- its own system prompt and the one message it was handed,
+ * nothing else -- and returns exactly one observation. The caller resumes, sees that
+ * observation as a tool result, and authors the final answer. The runtime primitive is
+ * `delegate`.
+ *
+ * So the observable difference is who produces the final answer, and whose transcript
+ * contains the other's messages: after a transfer the answer is the target's and the
+ * caller's steps are a prefix of the target's run; after a delegate the answer is the
+ * caller's and the delegate's transcript is a separate, closed conversation.
+ *
+ * Budgets are ratified decision D1: crossing one is a hard failure. An agent that declares
+ * `onBudgetExhausted: degrade` instead steps **one** rung down its declared alias ladder,
+ * **once**, and both the step record and the ledger show the cheaper alias. It is never a
+ * retry loop: a degraded frame that still does not fit fails.
+ *
+ * Span recording (`agent_span`, HITL and guardrail events) is not ported here: decision D-7
+ * defers agent-level tracing to the layer that also gives this runtime a tracer seam, and no
+ * conformance case observes a span. The observable behaviours the Python module records
+ * spans *for* -- status, steps, transfer target, degradation -- are all in `RunResult`.
+ */
+/** Namespacing for the control tools. A model cannot transfer by emitting prose. */
+export declare const TRANSFER_PREFIX = "transfer_to_";
+export declare const DELEGATE_PREFIX = "delegate_to_";
+/** The one argument a control tool takes: what the other agent needs to know. */
+export declare const CONTROL_ARGUMENT = "message";
+/** A step record while the loop is still deciding what the step did. */
+export type StepDraft = {
+    -readonly [K in keyof StepRecord]: StepRecord[K];
+};
+/** The memory context one agent turn resolved, and what it measured. */
+export interface MemoryState {
+    thread: ThreadMemory | undefined;
+    context: string;
+    scopes: readonly string[];
+    entries: number;
+    tokens: number;
+}
+/** One agent's turn in progress: its own transcript, budget anchors, and steps. */
+export interface Frame {
+    agent: AgentDefinition;
+    messages: Message[];
+    alias: string;
+    path: readonly string[];
+    step: number;
+    degraded: boolean;
+    memory: MemoryState;
+    memoryKey: string;
+    costAnchor: number;
+    tokenAnchor: number;
+    steps: StepDraft[];
+    resumedDecision: HumanDecision | undefined;
+    resumedChannel: string;
+    /**
+     * `input` runs once per frame, on the message the frame started from. A transferred
+     * target re-checks the conversation it inherited (its guardrails are its own), while a
+     * resumed frame does not: the checkpoint only exists because the input stage already ran.
+     */
+    inputChecked: boolean;
+    guardrails: GuardrailRecord[];
+}
+/** What a frame decided, before the run's totals are stamped on it. */
+export interface Outcome {
+    status: RunStatus;
+    agentId: string;
+    answer: string;
+    steps: readonly StepDraft[];
+    path: readonly string[];
+    checkpoint: AgentCheckpoint | undefined;
+    guardrails: readonly GuardrailRecord[];
+}
+export declare function outcomeOf(init: {
+    status: RunStatus;
+    agentId: string;
+    answer?: string;
+    steps: readonly StepDraft[];
+    path: readonly string[];
+    checkpoint?: AgentCheckpoint;
+    guardrails: readonly GuardrailRecord[];
+}): Outcome;
+/** Runs the IR's agents on the native engine. */
+export declare class AgentRuntime {
+    #private;
+    constructor(spec: RuntimeSpec, gateway: ModelGateway, options?: {
+        readonly tools?: Iterable<Tool>;
+        readonly stores?: Readonly<Record<string, MemoryStore>> | ReadonlyMap<string, MemoryStore>;
+        readonly memoryStore?: MemoryStore;
+        readonly limiter?: ConcurrencyLimiter;
+    });
+    /**
+     * Build a runtime from an emitted IR document.
+     *
+     * The IR's `deployments[].concurrency` becomes one limiter shared by the gateway and the
+     * tool executor, so model calls, tool calls, and delegation all draw from the same budget
+     * rather than running two independent pools.
+     */
+    static fromIr(document: Record<string, unknown>, options: {
+        readonly providers: Readonly<Record<string, Provider>>;
+        readonly tools?: Iterable<Tool>;
+        readonly stores?: Readonly<Record<string, MemoryStore>> | ReadonlyMap<string, MemoryStore>;
+        readonly memoryStore?: MemoryStore;
+        readonly ledger?: CostLedger;
+        readonly budget?: Budget;
+    }): AgentRuntime;
+    get spec(): RuntimeSpec;
+    get gateway(): ModelGateway;
+    /** Run `agentId` to a stop condition on one user message. */
+    run(agentId: string, text: string, options?: {
+        readonly principal?: Principal;
+        readonly memoryKey?: string;
+        readonly conversation?: readonly Message[];
+    }): Promise<RunResult>;
+    /** Continue a paused run from its checkpoint, with a human's answer. */
+    resume(checkpoint: AgentCheckpoint, decision: HumanDecision, options?: {
+        readonly principal?: Principal;
+    }): Promise<RunResult>;
+}
+//# sourceMappingURL=loop.d.ts.map

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

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