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

package/dist/extensions/types.d.ts

@@ -24,7 +24,7 @@
  * `ExtensionRuntime` is the façade that hides which physical channel a decision point arrives on;
  * extension authors only ever see one `api.on(...)` table.
  */
-import type { AgentEvent, AssistantMessage, ChatModel, AgentInput, ContextBreakdown, ConversationContext, Injector, LlmRequest, Machine, Message, ModelRuntime, RunResult, SessionSummary, PendingApprovalInterrupt, SessionStore, SteerContent, SteerOrigin, SteerReceipt, StepStopReason, TerminalStepStopReason, ThinkingLevel, Tool, ToolPlan, ToolResult, ToolResultContent, ToolRunContext, Usage } from "operon-agents-core";
+import type { AgentEvent, AssistantMessage, ChatModel, AgentInput, ContextBreakdown, ConversationContext, Injector, LlmRequest, Environment, Message, ModelRuntime, RunResult, SessionSummary, PendingApprovalInterrupt, SessionStore, SteerContent, SteerOptions, SteerOrigin, SteerReceipt, StepStopReason, TerminalStepStopReason, ThinkingLevel, Tool, ToolPlan, ToolResult, ToolResultContent, ToolRunContext, Usage } from "operon-agents-core";
 /** Per-extension key/value state, namespaced into the session store (memory without one). */
 /** A slash command an extension carries (see `ExtensionAPI.registerCommand`). The run
  *  receives only the raw argument string — an extension command closes over what it needs. */
@@ -57,7 +57,7 @@ export interface ExtensionState {
 export type ModelProvider = Parameters<ModelRuntime["models"]["setProvider"]>[0];
 /**
  * Operations that exist above the agent loop: other sessions, and the model provider registry.
- * Supplied by `Harness` when it builds the extensions capability. This is exactly why the
+ * Supplied by `Harness` when it builds an extension's capability. This is exactly why the
  * extension runtime lives in `operon-agents` and not in core — core has no concept of "another
  * session", so an interface defined down there would have been half stubs.
  *
@@ -107,17 +107,18 @@ export interface ExtensionHost {
 export interface HarnessSessionHandle {
     readonly id: string;
     prompt(input: AgentInput): Promise<RunResult>;
-    steer(input: string): string;
-    followUp(input: string): string | null;
+    steer(input: string): SteerReceipt;
+    followUp(input: string): SteerReceipt | null;
     /**
      * Hand a message to a specific frame in that session — `main` for its root agent,
-     * `main/<agentId>` for one of its subagents — carrying your own provenance. `false` when no
-     * frame is running there.
+     * `main/<agentId>` for one of its subagents — carrying your own provenance. Undefined when no
+     * frame is running there. The receipt's `steerId` (your own, via `options.id`, or minted) is
+     * what the recipient's journal carries as `origin.steerId` once the message is consumed.
      *
      * `steer`/`followUp` above can only ever reach the root; this is what lets an extension address
      * an individual subagent, which is what coordination between agents requires.
      */
-    steerTo(address: string, content: string, origin: SteerOrigin): boolean;
+    steerTo(address: string, content: string, origin: SteerOrigin, options?: SteerOptions): SteerReceipt | undefined;
     cancel(): void;
     close(): Promise<void>;
 }
@@ -195,7 +196,7 @@ interface ExtensionContextBase {
     readonly extensionId: string;
     readonly sessionId: string;
     readonly signal: AbortSignal;
-    readonly machine: Machine;
+    readonly environment: Environment;
     readonly store?: SessionStore;
     readonly state: ExtensionState;
     readonly actions: ExtensionActions;
@@ -204,18 +205,18 @@ interface ExtensionContextBase {
 export interface ExtensionEventContext extends ExtensionContextBase {
     readonly address: string;
 }
-/** Context for session-tier events, which have no active shard. */
-export interface ExtensionSessionContext extends ExtensionContextBase {
+/** Context for session-tier events (`session.start` / `session.end`), which have no active shard. */
+export interface ExtensionSessionEventContext extends ExtensionContextBase {
     readonly address?: never;
 }
-/** `attach` = added to a live session via `attachExtension`, after its `setup` succeeded. */
+/** `attach` = added to a live session via `attachExtension`, after its `session` succeeded. */
 export type SessionStartReason = "open" | "resume" | "fork" | "attach";
 /** `detach` = removed from a live session via `detachExtension`; fires before teardown. */
 export type SessionEndReason = "close" | "shutdown" | "detach";
-export interface ExtensionSessionStartEvent extends ExtensionSessionContext {
+export interface ExtensionSessionStartEvent extends ExtensionSessionEventContext {
     readonly reason: SessionStartReason;
 }
-export interface ExtensionSessionEndEvent extends ExtensionSessionContext {
+export interface ExtensionSessionEndEvent extends ExtensionSessionEventContext {
     readonly reason: SessionEndReason;
 }
 export interface ExtensionStepStartEvent extends ExtensionEventContext {
@@ -351,12 +352,10 @@ export interface ExtensionCompactionBeforeResult {
         readonly count?: number;
     };
 }
-/**
- * Headers a provider request carries. `null` deletes a header pi would otherwise send.
- * Mirrors pi-ai's `ProviderHeaders`, spelled out here so the extension contract does not
- * depend on a type core has no reason to re-export.
- */
-export type ProviderHeaders = Record<string, string | null>;
+/** Headers a provider request carries (`null` deletes a header) — core's type, the one
+ *  capability provider hooks use too. */
+export type { ProviderHeaders } from "operon-agents-core";
+import type { ProviderHeaders } from "operon-agents-core";
 /**
  * These three fire BELOW the loop: the runtime folds them into the request's
  * `providerOptions`, and pi-ai calls back from inside its HTTP path. Two consequences the
@@ -503,23 +502,24 @@ export interface ExtensionAPI {
     /**
      * This extension's own journal records, oldest first — the event-sourcing read path.
      * The open-time snapshot rides the session's single shared memoized log read (no extra
-     * traversal); records appended this session are included. Fold these in `setup` to rebuild
+     * traversal); records appended this session are included. Fold these in `session` to rebuild
      * sourced state; prefer `state` when a snapshot is all you need.
      */
     records(): Promise<readonly ExtensionRecordEntry[]>;
     /** Durable per-extension KV (SessionStore-backed) — the same facade handlers get via
-     *  `ctx.state`, available from `setup` so state can be loaded before the first run. */
+     *  `ctx.state`, available from `session` so state can be loaded before the first run. */
     readonly state: ExtensionState;
-    /** The same imperative surface handlers get via `ctx.actions`, usable from `setup`. */
+    /** The same imperative surface handlers get via `ctx.actions`, usable from `session`. */
     readonly actions: ExtensionActions;
 }
 /**
- * What an extension's `create` half is handed — the harness reach it needs to build a
+ * What an extension's `harness` half is handed — the harness reach it needs to build a
  * process-shared instance. Deliberately narrow: session creation (a spawn factory's one
- * requirement) and a data directory (the file form's own folder; absent by value). No
- * service-registration call: the instance IS the return value, registered under the extension's `id`.
+ * requirement), a data directory (the file form's own folder; absent by value) and the handles
+ * of the services it declared in `uses`. No service-registration call: the instance IS the
+ * return value, registered under the extension's `id`.
  */
-export interface ExtensionHostContext {
+export interface ExtensionHostContext<TServices extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
     /** Open a brand-new session on this harness — what a spawn factory calls. */
     createSession(options?: {
         readonly title?: string;
@@ -528,12 +528,20 @@ export interface ExtensionHostContext {
     } & Record<string, unknown>): Promise<{
         readonly id: string;
     }>;
+    /**
+     * Handles to the services named in `uses`, by name — the same handles `session` gets as
+     * `ctx.services`, available to the process half too. What lets a file-loaded bundle take its
+     * configuration from a host-registered service (`createHarness({ services })`) instead of
+     * baking it in: a reload re-runs `harness`, so re-reading the service IS the config update.
+     * Method calls resolve the CURRENT provider; the handles expose methods only.
+     */
+    readonly services: TServices;
     /** The extension's own folder when it was file-loaded; `undefined` when passed by value.
      *  Code only — an update replaces it wholesale. Keep files in `dataDir`. */
     readonly dir?: string;
     /**
      * Where this extension keeps its files: a folder of its own, by id, OUTSIDE the code folder,
-     * so replacing the bundle (update) leaves it untouched. Created before `create` runs. Present
+     * so replacing the bundle (update) leaves it untouched. Created before `harness` runs. Present
      * whenever the harness has a data root — `extensionDir` implies one (`<extensionDir>/.data`);
      * by value it is opt-in (`createHarness({ extensionDataDir })`).
      */
@@ -541,13 +549,16 @@ export interface ExtensionHostContext {
     warn(message: string): void;
 }
 /**
- * What `setup` receives besides the API: the handles the framework resolved for this extension
+ * What `session` receives besides the API: the handles the framework resolved for this extension
  * in this session. Nothing here is looked up by name from inside the extension — every service
- * it may touch was declared on the definition (`create` for its own, `uses` for others') and
+ * it may touch was declared on the definition (`harness` for its own, `uses` for
+ * others') and
  * arrives resolved.
  */
-export interface ExtensionSetupContext<TShared = unknown, TParams = unknown, TServices extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
-    /** Handle to this extension's own `create` result — `undefined` when it has no `create`. */
+export interface ExtensionSessionContext<TShared = unknown, TParams = unknown, TServices extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+    /** Handle to this extension's own shared instance — its `harness` result (one per process) or
+     *  its `workspace` result (this session's workspace's); `undefined` when it has neither. The
+     *  session half does not know, and need not know, which tier it lives at. */
     readonly shared: TShared;
     /** This session's per-session argument (`createSession({ params: { [id]: … } })`); `undefined` when none. */
     readonly params: TParams | undefined;
@@ -561,17 +572,17 @@ export interface ExtensionSetupContext<TShared = unknown, TParams = unknown, TSe
 /**
  * An extension: a programmatic participant assembled into a session. One definition, handed to
  * the framework once — by value in `createHarness({ extensions })` or from a file in
- * `extensionDir` — and mounted into every session from then on. Three parts, the first two
- * optional:
+ * `extensionDir` — and mounted into every session from then on. Four parts, the first three
+ * optional, named for the tier each one runs at (the same three tiers as `createHarness`'s
+ * `harness` / `workspace` / `session` hooks):
  *
- * - **`create` — the process-shared half.** Runs ONCE per harness, not per session. Its return
- *   value is registered as a service under this extension's `id`; every session's `setup` then
- *   receives a stable handle to it as `ctx.shared`. There is no separate type and no separate
- *   option for an extension with a `create` — only this field.
+ * - **`harness` — the process-shared half.** Runs ONCE per harness, not per session. Its return
+ *   value is registered as a service under this extension's `id` in the harness scope; every
+ *   session's `session` then receives a stable handle to it as `ctx.shared`.
  * - **`uses` — the services of others it consumes.** Names only; checked when the definition is
- *   registered (a consumer must come after its provider) and handed to `setup` resolved as
+ *   registered (a consumer must come after its provider) and handed to `session` resolved as
  *   `ctx.services[name]`. There is no lookup by name from inside an extension.
- * - **`setup` — the per-session half.** Runs once per session with the resolved context. A
+ * - **`session` — the per-session half.** Runs once per session with the resolved context. A
  *   session varies it with `createSession({ params: { [id]: … } })` — `ctx.params` — and opts
  *   out of it entirely with `false`.
  *
@@ -583,12 +594,11 @@ export interface ExtensionDefinition<TShared = unknown, TParams = unknown, TServ
     readonly id: string;
     /** Per-handler invocation budget. Defaults to 30s for decision points, 1s for observers. */
     readonly timeoutMs?: number;
-    /** The process-shared half. Absent ⇒ an ordinary per-session extension. See above. */
-    create?(host: ExtensionHostContext): TShared | Promise<TShared>;
-    /** Services this extension consumes, by name — other extensions' `create` results (their
-     *  `id`s) or host-registered `services`. Resolved into `ctx.services` for `setup`. */
+    /** The process-shared half: once per harness. See above. */
+    harness?(host: ExtensionHostContext<TServices>): TShared | Promise<TShared>;
+    /** Services this extension consumes, by name — other extensions' shared-half results (their
+     *  `id`s) or host-registered `services`. Resolved into `ctx.services` for `session`. */
     readonly uses?: readonly (keyof TServices & string)[];
-    setup(api: ExtensionAPI, ctx: ExtensionSetupContext<TShared, TParams, TServices>): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+    session(api: ExtensionAPI, ctx: ExtensionSessionContext<TShared, TParams, TServices>): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
 }
-export {};
 //# sourceMappingURL=types.d.ts.map