melchizedek-agents 0.18.0 → 0.20.0

package/dist/lib/runtime/memoryService.js

@@ -0,0 +1,25 @@
+/**
+ * lib/runtime/memoryService.ts — the engine's own long-term memory interface
+ * (ADR 0045, ADR 0052).
+ *
+ * WHY this file exists:
+ *   The native runtime asks long-term memory for what it needs through this
+ *   interface, never through ADK's BaseMemoryService. The engine's service
+ *   (lib/memory/supabaseMemoryService.ts) implements it, and also ADK's
+ *   interface, whose methods hand their arguments to this one's, so the ADK
+ *   runtime reaches the same logic (ADR 0059). The shapes include the
+ *   extras: per-syndicate extraction rules and model, erasure, retention and
+ *   the boot-time dimension check, which the A2A server reaches by name
+ *   (lib/a2a/app.ts). The memory tools reach `search` through the tool
+ *   context's `searchMemory` (lib/tools/tool.ts, lib/tools/memoryTools.ts).
+ *
+ * SILOS: every fact is filed under `<appName>/<userId>`, and a search reads
+ * that key alone. `appName` is the memory namespace, not the agent that
+ * asks: the runtime pins it to the root syndicate's `memory_namespace`
+ * (lib/memory/namespace.ts, ADR 0020), so a subagent finds what its
+ * orchestrator's conversations stored.
+ *
+ * Types only, and every import is a type: nothing in this module's import
+ * graph names @google/* (tests/events.test.ts asserts it).
+ */
+export {};

package/dist/lib/runtime/native/agentLoop.d.ts

@@ -0,0 +1,209 @@
+/**
+ * lib/runtime/native/agentLoop.ts — the native loop for one agent: a model
+ * step, the step's tool calls, their results fed back, until the model
+ * stops calling tools or the turn stops it (ADR 0045, ADR 0066).
+ *
+ * WHY this file exists:
+ *   On the ADK runtime this is LlmAgent.runAsyncImpl: run one step
+ *   (lib/runtime/native/step.ts is the native step), run the answer's
+ *   function calls (ADK's handleFunctionCallList), store the response
+ *   event, and step again unless the last event is a final response. A
+ *   session either runtime wrote must be one the other continues, so every
+ *   event this loop stores is the one ADK stores for the same answer and the
+ *   same tool results, ids and times aside. tests/nativeLoop.test.ts runs
+ *   the boundary suite's single-agent cases both ways and compares.
+ *
+ * ONE STEP, AS ADK RUNS IT:
+ *   1. The model step (runModelStep). Its partial events are yielded as they
+ *      arrive and stored nowhere, so drainAgentStream hands their text to
+ *      onTextDelta exactly as it does on the ADK path. With a
+ *      `fallback_model`, the step runs once per leaf adapter (ADR 0053): a
+ *      provider-side failure before anything was produced is not stored,
+ *      and the fallback answers the same request under its own model id, by
+ *      ADK's FallbackLlm's rules and the shared circuit breaker (ADR 0044).
+ *   2. The answer's calls run in parallel, each with its own context (its
+ *      own state delta and actions). Results are kept in call order:
+ *      - a call naming no declared tool answers
+ *        `{ error: "Function <name> is not found in the toolsDict." }`;
+ *      - a tool that throws answers `{ error: "Error in tool '<name>': …" }`,
+ *        the text ADK's FunctionTool writes (lib/tools/adkTool.ts);
+ *      - with self-correction's tool side on (retries.tool_errors, default
+ *        3), those two answer with reflection guidance instead, counted per
+ *        tool in call order (lib/runtime/native/selfCorrection.ts);
+ *      - a tool that requires approval and has none asks for it, as
+ *        FunctionTool's gate does: `{ error: APPROVAL_TEXTS.pending }`,
+ *        `skipSummarization`, and the request under the call's id;
+ *      - a long-running tool (ask_user) that returns nothing answers
+ *        nothing; its actions, when it set any, make an event of their own;
+ *      - a result that is not an object is wrapped `{ result }`, an array
+ *        `{ results }`, as ADK wraps them;
+ *      - a result nested deeper than MAX_VALUE_DEPTH levels answers
+ *        `{ error: TOO_DEEP_RESULT }` instead: every later reader of the
+ *        session would overflow its stack on it (lib/runtime/valueDepth.ts,
+ *        ADR 0101). ADK keeps it.
+ *      One call's response is stored as its own event; several are merged
+ *      into one, parts in call order and actions merged (ADK's
+ *      mergeParallelFunctionResponseEvents). ADK runs the calls one after
+ *      another and lets a call read the state an earlier call of the same
+ *      step wrote; here each call reads the state as the step left it.
+ *   3. An approval request ends the run: the response is NOT stored; in its
+ *      place the event ADK stores, a call to `adk_request_confirmation`
+ *      (args: the original call and the confirmation; an `adk-` id listed in
+ *      longRunningToolIds), carrying the response's actions. The answer
+ *      resumes it: before each step, lib/runtime/native/interrupts.ts runs
+ *      the pinned call the latest user message approves or refuses, as ADK's
+ *      request-confirmation processor does, and its response is stored
+ *      before the request is built.
+ *   4. The agent's outputKey is written into each final event's stateDelta
+ *      before it is stored (ADK's maybeSaveOutputToState, case for case).
+ *      The `temp:` keys of every event stored are kept for the rest of the
+ *      run, beside the session and never in it, and each later step and
+ *      call reads them (lib/runtime/native/tempState.ts).
+ *   5. The loop goes on unless the step's last event is final (ADK's
+ *      isFinalResponse), the turn stopped the step, or the step stored
+ *      nothing. A model call that waits on a person (ask_user) is final: its
+ *      model event lists the call in longRunningToolIds, and the run ends
+ *      with no response to it, the call pending. The answer resumes it: the
+ *      turn runner stores the person's next message as the call's function
+ *      response, and the next run's first step reads the call and its answer
+ *      from the history (history.ts), as ADK's content processor does. No
+ *      request processor acts on it (ADR 0079).
+ *
+ * DELEGATION: a call to a subagent tool runs the subagent as its own child
+ * loop, as ADK's AgentTool runs it (lib/runtime/native/delegate.ts, ADR 0074).
+ *
+ * SELF-CORRECTION (ADR 0034, ADR 0075) is ADK's reflect-and-retry plugins,
+ * ported to lib/runtime/native/selfCorrection.ts: the step declares the
+ * reflection tool and passes each response through its model side, and
+ * each call's error or answer goes through its tool side. On by default,
+ * as runSyndicateTurn installs the plugins by default.
+ *
+ * COMPACTION (ADR 0033): with the agent's `context:`, each step may first
+ * store ADK's compacted event, written by the summary model
+ * (lib/runtime/native/compaction.ts). It is yielded like any stored event
+ * and is not the run's `lastEvent`.
+ *
+ * TASK MODE (ADR 0033, ADR 0081): finish_task is an own tool the request
+ * declares; a run marked `taskNode` ends on its successful answer
+ * (lib/runtime/native/taskMode.ts).
+ *
+ * WORKFLOW NODES (ADR 0090): a run for a workflow agent node passes
+ * `nodeStamp`, which writes the node's output and path on each event before
+ * it is stored (lib/workflow/agentNode.ts).
+ *
+ * CONSENT (WS6-3b, ADR 0085): with `credentials`, each call's
+ * `accessToken(provider)` reads the user's grant (ADR 0072). With `consent`,
+ * a call whose provider the user has not granted asks for it
+ * (`requestCredential`, or `accessToken` by itself): the call answers
+ * CONSENT_TEXTS.pending, ADK's `adk_request_credential` event is stored
+ * before the response (ADK's generateAuthEvent), and the run ends paused on
+ * it. The flow's secrets stay in the consent step (lib/tools/oauthConsent.ts).
+ * Before each step, a credential request the latest user message answers
+ * runs its paused call again (interrupts.ts grantedCalls, ADK's auth
+ * preprocessor), ahead of the approval resume.
+ *
+ * NOT HERE (later tickets): transfer_to_agent (no compiled syndicate sets
+ * subAgents). The run's spans (agent.invoke, model.call,
+ * tool.execute) are lib/runtime/native/telemetry.ts.
+ *
+ * ADK stays out of this file: an ADK tool an agent still lists during the
+ * dual period (a registry FunctionTool, the skills toolset's tools) is run
+ * through its runAsync with a context shaped like ADK's, by shape.
+ */
+import type { ModelAdapter } from '../../models/contract.ts';
+import type { CredentialStore } from '../../tools/auth.ts';
+import type { OAuthConsent } from '../../tools/oauthConsent.ts';
+import type { TurnEvent } from '../events.ts';
+import type { NativeAgent } from './request.ts';
+import { SelfCorrection } from './selfCorrection.ts';
+import type { ModelStepOptions, StepStop } from './step.ts';
+/**
+ * Where one agent runs: what runModelStep takes besides the agent and its
+ * adapter. The session already holds the run's user event; every event the
+ * loop stores is appended to it.
+ */
+export interface AgentLoopContext extends Omit<ModelStepOptions, 'agent' | 'adapter' | 'onPartial' | 'model' | 'beforeAppend' | 'redirect' | 'correction' | 'stateOverlay'> {
+    /** The leaf adapter for a model id: the agent's, and its fallback's. Default resolveAdapter (lib/models/registry.ts). */
+    adapterFor?: (model: string) => ModelAdapter;
+    /** Where the fallback's redirect notice goes. Default console.warn, as compile's. */
+    log?: (message: string) => void;
+    /**
+     * Self-correction (ADR 0034, ADR 0075): the turn's one instance, built from
+     * the syndicate's `retries:`. Default: retries at their defaults, as
+     * runSyndicateTurn installs ADK's plugins by default.
+     */
+    selfCorrection?: SelfCorrection;
+    /**
+     * The run is a `mode: task` workflow node's (ADK's runTaskMode): it ends
+     * once finish_task answers with success, that event carrying the node's
+     * output (lib/runtime/native/taskMode.ts). Default false: a plain run
+     * goes on after finish_task's answer, as LlmAgent.runAsync does.
+     */
+    taskNode?: boolean;
+    /**
+     * The run is a workflow node's: called on each event before it is stored,
+     * after the outputKey and task hooks, as ADK's node runner stamps an event
+     * (its output, `nodeInfo.path` and `outputFor`) before its Runner appends
+     * it (lib/workflow/agentNode.ts). Not passed to a delegated subagent's loop.
+     */
+    nodeStamp?: (event: TurnEvent) => void;
+    /**
+     * The run's tool credentials, already pinned to its app
+     * (pinnedCredentialStore, ADR 0072): each call's `accessToken` reads them
+     * under the session's user.
+     */
+    credentials?: Pick<CredentialStore, 'get'>;
+    /**
+     * The consent step (ADR 0085): a call whose provider the user has not
+     * granted asks for it (`requestCredential`, or `accessToken` by itself),
+     * and the run pauses on ADK's `adk_request_credential` call. Not passed to
+     * a delegated subagent's loop.
+     */
+    consent?: Pick<OAuthConsent, 'has' | 'begin'>;
+}
+/** How the run ended. */
+export type AgentLoopEndReason = 
+/** The last event is a final answer (text, a set_model_response answer, a response that skips summarization). */
+'final'
+/** A call waits on a person: an ask_user call, or an approval request. `pending` holds the ids. */
+ | 'paused'
+/** The last event carries an error (a failed model call), as the ADK path stores it. */
+ | 'error'
+/** The turn stopped a step (cancel, deadline, max_steps): no event was stored for it. */
+ | 'stopped'
+/** The model answered nothing: no parts, no error, no usage. */
+ | 'empty';
+export interface AgentLoopEnd {
+    reason: AgentLoopEndReason;
+    /** Model steps run (a fallback's answer counts with the step it answered). */
+    steps: number;
+    /** The last event stored. */
+    lastEvent?: TurnEvent;
+    /** For `paused`: the ids waiting on a person (the ask_user call ids, or the adk_request_confirmation call ids). */
+    pending?: string[];
+    /** For `stopped`: the turn's code and message. */
+    stop?: StepStop;
+    /** For a task-mode node's run that finished: the finish_task arguments, extracted (lib/runtime/native/taskMode.ts). */
+    output?: unknown;
+}
+/**
+ * Writes the agent's final answer into `event`'s stateDelta under its
+ * outputKey: the text of its parts; with an output schema, the parsed and
+ * validated JSON (the text itself when it does not parse; the parsed value
+ * when it does not validate).
+ */
+export declare function saveOutput(agent: Pick<NativeAgent, 'name' | 'outputKey' | 'outputSchema'>, event: TurnEvent): void;
+/** What a tool's result becomes when it nests past MAX_VALUE_DEPTH (ADR 0101). */
+export declare const TOO_DEEP_RESULT: (toolName: string) => string;
+/**
+ * Runs `agent` on the session in `ctx` until its answer is final, yielding
+ * every event in order: partials as they arrive (never stored), then each
+ * event as the store returned it. Returns how the run ended.
+ *
+ * Never throws for a failed model call or a failing tool: the first is the
+ * last event, stored with its error, the second the call's error response.
+ * An adapter that throws an Error ends the step on ADK's error event for
+ * it (lib/runtime/native/step.ts). Throws where the ADK runtime throws: a
+ * request that cannot be built, a store that throws.
+ */
+export declare function runAgentLoop(agent: NativeAgent, ctx: AgentLoopContext): AsyncGenerator<TurnEvent, AgentLoopEnd>;