operon-agents 0.1.0-alpha.0

package/dist/extensions/runtime.d.ts

@@ -0,0 +1,188 @@
+import type { HeadlessCommand } from "operon-agents-core";
+import type { AssistantMessage, CapabilityContext, CompactionGate, ChatModel, ConversationContext, Injector, LlmRequest, Message, SessionContext, StepStopReason, TerminalStepStopReason, Tool, ToolPlan, ToolResult, Usage } from "operon-agents-core";
+import type { ExtensionDefinition, ExtensionHost, ExtensionModelRequestResult, ExtensionStepEndResult, ExtensionStepStartResult, ExtensionToolAuthorizeResult, ExtensionToolCallResult, SessionEndReason, SessionStartReason } from "./types.ts";
+/** Shared shape of the loop-hook contexts the dispatch methods are fed from. */
+interface StepOrigin {
+    readonly turnId: string;
+    readonly stepNumber: number;
+    readonly address?: string;
+    readonly signal: AbortSignal;
+    readonly model: ChatModel;
+}
+export declare class ExtensionRuntime {
+    private readonly definitions;
+    private readonly handlers;
+    private readonly tools;
+    /** Stable reference: `extensionsCapability` hands this array to the assembler, and `setup`
+     *  (which runs at openSession, before any run assembles) fills it in place. */
+    private readonly injectors;
+    /** Slash commands by normalized name — surfaced to the session's registry via the
+     *  `sessionCommands()` duck protocol. Two extensions claiming one name fail closed. */
+    private readonly extCommands;
+    /** Host-facing control surfaces published via `api.expose`, by extension id. */
+    private readonly exposedHandles;
+    /** Records read path: open-time snapshot buckets (built lazily off the session's shared
+     *  memoized log read — zero extra traversal) + everything recorded this session. */
+    private recordSnapshot;
+    private readonly recordWrites;
+    /** Per-extension teardown: setup's cleanup + every registration, undone in reverse. */
+    private readonly scopes;
+    /** Extensions whose contributions are currently honored. An id leaves on detach (and on
+     *  setup failure), which turns every `actions`/`api` closure the extension still holds
+     *  into a warn-and-noop — a detached extension must not keep steering the session. */
+    private readonly live;
+    /** Changes wait here until a quiet point: mid-run requests apply at the run's stop
+     *  boundary, so a turn never sees its toolset change underneath it. */
+    private pending;
+    /** Serializes flushes so concurrent attach/detach apply strictly in submission order. */
+    private flushChain;
+    private readonly memoryState;
+    private session;
+    private run;
+    /** The conversation shard the in-flight decision point belongs to; backs `actions.record`. */
+    private activeContext;
+    /** Snapshot of the last assembled registry, refreshed once per turn by `filterTools`. */
+    private allToolNames;
+    /** `null` = unrestricted. Set by `actions.setActiveTools`; applied at the next assembly. */
+    private activeToolNames;
+    private reportingWarning;
+    /** Harness reach. Absent when the capability is built standalone (bare Runner / tests). */
+    private readonly host;
+    /** This session's per-session extension arguments, by extension id. A value of `false` means
+     *  "skip this extension for this session"; any other value is passed to `setup` as `params`. */
+    private readonly params;
+    constructor(definitions: readonly ExtensionDefinition[], host?: ExtensionHost, params?: Readonly<Record<string, unknown>>);
+    open(ctx: SessionContext, reason?: SessionStartReason): Promise<void>;
+    attachRun(ctx: CapabilityContext): void;
+    detachRun(): Promise<void>;
+    close(reason?: SessionEndReason): Promise<void>;
+    /**
+     * Add an extension to the live session. Resolves once its `setup` has run and its
+     * contributions are in place — with no run in flight that is immediately; mid-run it is
+     * the current run's stop boundary, so an in-flight turn never sees its registry change.
+     * Rejects on duplicate/empty id or when `setup` throws.
+     */
+    attach(definition: ExtensionDefinition): Promise<void>;
+    /** Ids of currently attached extensions — the reshape coordinator's affected-set probe. */
+    attachedIds(): readonly string[];
+    /** Currently attached extensions with what each declared it `uses` — the unload consumer scan. */
+    attachedExtensions(): readonly {
+        readonly id: string;
+        readonly uses: readonly string[];
+    }[];
+    /** The duck protocol the session's command registry consumes: dynamic commands contributed
+     *  by attached extensions (`api.registerCommand`). */
+    sessionCommands(): readonly HeadlessCommand[];
+    /** The control surface `extensionId` published via `api.expose`; undefined when absent
+     *  (never attached, detached, or nothing exposed). */
+    exposedHandle<T = unknown>(extensionId: string): T | undefined;
+    /** Remove an extension: its `session.end` fires, then its whole scope is torn down. */
+    detach(id: string): Promise<void>;
+    private submit;
+    private flushPending;
+    private drainPending;
+    private attachNow;
+    private detachNow;
+    /** Runs one extension's `setup` and files its scope. Failure ⇒ skipped, contributions undone. */
+    private setupExtension;
+    /**
+     * Durable audit trail: replay needs "tool X only exists after record N" to reconstruct the
+     * capability timeline. Rides the `custom` record type — audit-only, ignored by reducers.
+     */
+    private logChange;
+    listTools(): readonly Tool[];
+    listInjectors(): readonly Injector[];
+    /**
+     * The capability's `ToolFilter`. Snapshots the full registry (so `getAllTools` has something
+     * to report) and applies the active-tool restriction, if any. Identity-returns when nothing
+     * is restricted, which lets the caller skip rebuilding the deferred-name set.
+     */
+    filterTools: (tools: readonly Tool[]) => readonly Tool[];
+    /**
+     * Run-tier: the caller's input, before guardrails and before anything is journaled.
+     * There is no active conversation yet, so this borrows the session context's shape.
+     */
+    beforeRun(origin: {
+        readonly address: string;
+        readonly agent: string;
+        readonly signal: AbortSignal;
+    }, input: readonly Message[]): Promise<{
+        input?: readonly Message[];
+        handled?: {
+            output?: string;
+        };
+    } | undefined>;
+    /**
+     * The capability's compaction gate. Not engine-driven: the compaction capability calls this
+     * through core's `CapabilityGates`, which is why there is no matching `LoopHooks` slot.
+     *
+     * There is no run-scoped address here (compaction is a session-level operation on one shard),
+     * so handlers get the session context shape plus the shard being compacted.
+     */
+    compactionGate: CompactionGate;
+    beforeStep(origin: StepOrigin, context: ConversationContext, system: string | undefined): Promise<ExtensionStepStartResult | undefined>;
+    afterStep(origin: StepOrigin, context: ConversationContext, usage: Usage, stopReason: StepStopReason): Promise<ExtensionStepEndResult | undefined>;
+    runSettled(origin: StepOrigin, usage: Usage, stopReason: TerminalStepStopReason): Promise<{
+        continue: boolean;
+    } | undefined>;
+    beforeModelRequest(origin: StepOrigin, request: LlmRequest, context: ConversationContext): Promise<ExtensionModelRequestResult | undefined>;
+    /**
+     * Attach `transformHeaders` / `onPayload` / `onResponse` when anything is listening. Returns
+     * `undefined` when nothing is, so a request with no provider-tier extensions is left byte-identical.
+     *
+     * These fire once per HTTP ATTEMPT, so a retry re-runs them — the contract tells handlers to be
+     * idempotent, and the runtime does not try to dedupe on their behalf.
+     */
+    private withProviderHooks;
+    afterModelResponse(origin: StepOrigin, request: LlmRequest, response: AssistantMessage, context: ConversationContext): Promise<AssistantMessage | undefined>;
+    beforeToolCall(origin: StepOrigin, toolName: string, toolCallId: string, tool: Tool | undefined, args: unknown): Promise<ExtensionToolCallResult | undefined>;
+    authorizeToolCall(origin: StepOrigin, toolName: string, toolCallId: string, tool: Tool | undefined, args: unknown, plan: ToolPlan): Promise<ExtensionToolAuthorizeResult | undefined>;
+    afterToolResult(origin: StepOrigin, toolName: string, toolCallId: string, tool: Tool | undefined, args: unknown, result: ToolResult): Promise<ToolResult | undefined>;
+    private apiFor;
+    /**
+     * A handle to service `name` collared to `extensionId`'s liveness — the `actions` revocation
+     * collar mirrored: liveness is checked at CALL time, including for METHODS stashed off the
+     * handle before detach (the returned function re-checks on every invocation), so nothing
+     * handed out while live keeps operating afterwards. The inner registry handle decides the
+     * probe/shape questions (probes read undefined, field access throws); only functions get
+     * the wrapper.
+     */
+    private serviceHandle;
+    /** viaHost-backed actions promise session handles; when revoked they must reject, not fake. */
+    private static readonly PROMISE_ACTIONS;
+    /**
+     * Revocation collar: a detached extension's stashed `actions` must not keep operating the
+     * session. Liveness is checked at CALL time (not build time), so closures handed out before
+     * the detach die with it. Reads (`hasActiveRun`) pass through — a stale read is harmless,
+     * a stale steer/abort is not.
+     */
+    private revocable;
+    private actionsFor;
+    /**
+     * Extension-originated prompts ride the `external` steer origin — they ARE an outside source
+     * as far as the transcript is concerned, and reusing it keeps the persisted `PromptOrigin`
+     * schema untouched. `source` names the extension so a fold can attribute the message.
+     */
+    private enqueue;
+    private controls;
+    /**
+     * Host-backed action wrapper. Rejects (rather than silently resolving to something fake) when
+     * no host is present — these return values are session handles a caller would go on to use, so
+     * a no-op would just move the failure somewhere less obvious.
+     */
+    private viaHost;
+    private sessionContext;
+    private eventContext;
+    /** Open-time record buckets, built ONCE off the session's shared memoized log read — the
+     *  same single read goal/plan/todo fold from, so `records()` adds zero log traversals. One
+     *  filter pass buckets every extension's records; ids are colon-free slugs so the
+     *  "extension:<id>:" prefix parse is unambiguous. */
+    private ensureRecordSnapshot;
+    private stateFor;
+    private handlersFor;
+    private invoke;
+    private warn;
+    private requireSession;
+}
+export {};
+//# sourceMappingURL=runtime.d.ts.map