operon-agents 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/extensions/runtime.d.ts

@@ -1,5 +1,6 @@
-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 { Environment, EventSink, SteerBus } from "operon-agents-core";
+import type { AgentRecord, HeadlessCommand } from "operon-agents-core";
+import type { AssistantMessage, CapabilityProviderHooks, RunContext, CompactionGate, ChatModel, ConversationContext, Injector, LlmRequest, Message, SessionContext, SessionControls, SessionStore, 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 {
@@ -9,37 +10,48 @@ interface StepOrigin {
     readonly signal: AbortSignal;
     readonly model: ChatModel;
 }
+/**
+ * The session services the extensions capability declares (see `extensionsCapability`). Named
+ * here because this is where they are used; the declaration that fills it lives next to the
+ * capability, so the two can be checked against each other by eye.
+ */
+export interface ExtensionServices {
+    readonly environment: Environment;
+    readonly events: EventSink;
+    readonly steer: SteerBus;
+    readonly controls: SessionControls;
+    readonly readLog: () => Promise<readonly AgentRecord[]>;
+    readonly store: SessionStore | undefined;
+}
+/**
+ * One extension, running in one session. `extensionCapability` wraps it as that session's
+ * capability, so everything around the extension — assembly, hook isolation, attach and detach
+ * at a run boundary, its state and records — is the engine's, the same as for any capability.
+ * What is left here is the translation the extension API exists for: `api` registrations into
+ * capability parts, and the engine's decision points into the extension's event vocabulary.
+ */
 export declare class ExtensionRuntime {
-    private readonly definitions;
+    readonly definition: ExtensionDefinition;
     private readonly handlers;
     private readonly tools;
-    /** Stable reference: `extensionsCapability` hands this array to the assembler, and `setup`
+    /** Stable reference: `extensionCapability` hands this array to the assembler, and `session`
      *  (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;
+    /** Slash commands, filled in place by `api.registerCommand` — the capability's `commands`. */
+    readonly commands: HeadlessCommand[];
+    /** The host-facing control surface published via `api.expose`. */
+    private exposed;
+    /** `session()`'s cleanup plus every registration, undone in reverse. */
+    private teardown;
+    /** False until `session` has run, and again once the extension is closed: every `actions` /
+     *  `api` closure it still holds turns into a warn-and-noop — a detached extension must not
+     *  keep steering the session. */
+    private live;
+    /** The session binding: the services the capability DECLARED, plus the session's id/signal. */
     private session;
     private run;
-    /** The conversation shard the in-flight decision point belongs to; backs `actions.record`. */
+    /** The conversation shard the in-flight decision point belongs to — the address a
+     *  `compaction.before` handler is told about. */
     private activeContext;
     /** Snapshot of the last assembled registry, refreshed once per turn by `filterTools`. */
     private allToolNames;
@@ -48,46 +60,31 @@ export declare class ExtensionRuntime {
     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`. */
+    /** This session's argument for the extension (`createSession({ params: { [id]: … } })`). */
     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>;
+    /** What `session.start` reports: `attach` for an extension added to a live session. */
+    private readonly startReason;
+    constructor(definition: ExtensionDefinition, options?: {
+        readonly host?: ExtensionHost;
+        readonly params?: unknown;
+        readonly startReason?: SessionStartReason;
+    });
+    get id(): string;
+    /** Run `session` and fire `session.start`. Throws when `session` does — the capability is then
+     *  absent from the session, with nothing it registered left behind. */
+    open(services: ExtensionServices, ctx: SessionContext): Promise<void>;
+    attachRun(ctx: RunContext): void;
+    detachRun(): void;
+    /** Fire `session.end` while the handlers are still registered, then unwind everything. */
     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. */
+    /** The control surface published via `api.expose`; undefined when nothing is (or it was
+     *  disposed, or the extension is closed). */
+    exposedHandle<T = unknown>(): T | undefined;
+    /** Runs one extension's `session` 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.
+     * Durable audit trail of when this extension joined or left the session — written to the
+     * session's audit shard, which nothing replays from.
      */
     private logChange;
     listTools(): readonly Tool[];
@@ -127,13 +124,17 @@ export declare class ExtensionRuntime {
     } | 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.
+     * The capability's provider hooks — `provider.headers` / `payload` / `response`. The engine
+     * composes them into the request with every other capability's, so two extensions rewriting
+     * headers both take effect instead of the second replacing the first. They 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;
+    readonly providerHooks: CapabilityProviderHooks;
+    /** Whether any provider-tier handler is registered — the capability omits `provider` otherwise,
+     *  so a request with no provider-tier extension is left byte-identical. */
+    hasProviderHandlers(): boolean;
+    private providerContext;
     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>;
@@ -173,12 +174,6 @@ export declare class ExtensionRuntime {
     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;