@rowan-agent/agent 0.6.0 → 0.6.1

package/README.md

@@ -20,14 +20,13 @@ or reconstruct an `Agent`, submit input with `send()`, and wait on the returned
 import {
   AgentRuntime,
   InMemoryRuntimeStateStore,
-  InMemorySessionProvider,
+  InMemorySessionStore,
   createCoreTools,
 } from "@rowan-agent/agent";
-import { createModelStream } from "@rowan-agent/models";
 
 const runtime = await AgentRuntime.start({
   stateStore: new InMemoryRuntimeStateStore(),
-  sessionProvider: new InMemorySessionProvider(),
+  sessionProvider: new InMemorySessionStore(),
 });
 
 try {
@@ -42,8 +41,13 @@ try {
         entryPhaseId: default,
       },
     },
-    model: { provider: "openai", id: "gpt-4.1-mini" },
-    stream: createModelStream(),
+    model: {
+      provider: "openai",
+      id: "gpt-4.1-mini",
+      protocol: "openai-completions",
+      baseUrl: "https://api.openai.com/v1",
+      apiKey: process.env.OPENAI_API_KEY!,
+    },
   });
 
   agent.subscribe((event) => console.log(event.type));
@@ -67,11 +71,17 @@ Exactly one `AgentRuntime` may be active in a process. It is the sole owner of
 Agent creation and reconstruction, durable input, scheduling, leases, Runtime
 Events, and Tool Call control. Always stop it during host shutdown.
 
+```ts
+type RuntimeEventConsumer = {
+  caughtUp: Promise<void>;
+  stop(): void;
+};
+```
+
 ```ts
 type AgentRuntimeOptions = {
   stateStore: InMemoryRuntimeStateStore | SqliteRuntimeStateStore;
-  sessionProvider?: InMemorySessionProvider | LocalJsonlSessionProvider;
-  factories?: ReadonlyMap<string, AgentFactory> | Readonly<Record<string, AgentFactory>>;
+  sessionProvider?: InMemorySessionStore | JsonlSessionStore;
   toolPolicy?: ToolRuntimePolicy;
   maxConcurrentRuns?: number;
   maxInfrastructureAttempts?: number;
@@ -81,15 +91,20 @@ type AgentRuntimeOptions = {
 
 class AgentRuntime {
   static start(options: AgentRuntimeOptions): Promise<AgentRuntime>;
-  createAgent(options: AgentCreateOptions): Promise<Agent>;
+  createAgent(options: AgentOptions): Promise<Agent>;
   reconstructAgent(agentId: AgentId, options: AgentOptions): Promise<Agent>;
   pauseAgent(agentId: AgentId): Promise<void>;
   resumeAgent(agentId: AgentId): Promise<void>;
+  getMessage(messageId: RuntimeMessageId): Promise<RuntimeMessage | undefined>;
+  getToolCall(toolCallId: RuntimeToolCallId): Promise<RuntimeToolCall | undefined>;
+  getRun(runId: AgentRunId): Promise<AgentRunRecord | undefined>;
+  listRuns(input?: { agentId?: AgentId; states?: AgentRunRecord["state"][] }): Promise<AgentRunRecord[]>;
+  listActiveRuns(): Promise<AgentRunRecord[]>;
   abortRun(runId: AgentRunId, reason?: string): Promise<void>;
   consumeEvents(
     consumerId: string,
-    listener: (event: RuntimeEvent) => void | Promise<void>,
-  ): () => void;
+    listener: RuntimeEventListener,
+  ): RuntimeEventConsumer;
   listEvents(cursor?: RuntimeEventCursor): Promise<RuntimeEvent[]>;
   stop(): Promise<void>;
 }
@@ -101,7 +116,7 @@ Runtime State and conversation history are deliberately separate:
 | Concern | Durable adapter | In-memory adapter |
 |---------|-----------------|-------------------|
 | Agent records, Messages, Runs, Leases, Runtime Events, Tool Calls | `SqliteRuntimeStateStore` | `InMemoryRuntimeStateStore` |
-| Conversation messages, model transcripts, Outcomes | `LocalJsonlSessionProvider` | `InMemorySessionProvider` |
+| Conversation messages, model transcripts, Outcomes | `JsonlSessionStore` | `InMemorySessionStore` |
 
 The SQLite Runtime schema has no compatibility migration. Replace an older
 Runtime database when adopting a breaking schema; Session JSONL records remain
@@ -119,35 +134,20 @@ The Runtime renews active leases and retries them up to
 `maxInfrastructureAttempts`; exhausted work fails and its triggering Message is
 dead-lettered.
 
-### Factory Recovery
+### Process Recovery
 
-An optional opaque Factory ID lets the Runtime reconstruct active Agents after
-a restart. The Factory supplies current executable resources; Rowan persists
-the Agent and Session identities, not model clients, Tools, Phases, or
-Extensions.
+Runtime startup recovers abandoned Leases into durable queued work without
+constructing Agent Bindings. The host supplies its current executable resources
+when it reconstructs an Agent:
 
 ```ts
-const factoryId = "coding-agent";
-const factories = new Map([
-  [factoryId, async () => currentAgentOptions],
-]);
-
-const runtime = await AgentRuntime.start({
-  stateStore,
-  sessionProvider,
-  factories,
-});
-
-const agent = await runtime.createAgent({
-  ...currentAgentOptions,
-  factoryId,
-});
+const runtime = await AgentRuntime.start({ stateStore, sessionProvider });
+const agent = await runtime.reconstructAgent(agentId, currentAgentOptions);
 ```
 
-On the next `AgentRuntime.start()` with the same durable adapters and Factory,
-the active Agent is reconstructed with its original Agent ID and Session ID.
-Missing or declining Factories leave the Agent unbound and emit a durable
-Runtime Event.
+Reconstruction preserves the Agent ID and Session ID. Establishing the Binding
+automatically schedules queued Runs. A suspended Agent may remain unbound until
+the host has new input, then reconstruct before calling `send()`.
 
 ## Agent
 
@@ -174,10 +174,18 @@ class Agent {
 ### AgentOptions
 
 ```ts
-type AgentOptions = {
+type ModelConfig = ModelRef & {
+  protocol: Protocol;
+  baseUrl: string;
+  apiKey: string;
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+  maxRetries?: number;
+  retryDelayMs?: number;
+};
+
+type AgentCommonOptions = {
   context: AgentContext;
-  model: LlmModelRef;
-  stream: StreamFn;
   cwd?: string;
   extensions?: LoadedExtension[];
   maxAttempts?: number;
@@ -185,17 +193,15 @@ type AgentOptions = {
   // Lifecycle hooks
   beforeToolCall?: BeforeToolCall;
   afterToolCall?: AfterToolCall;
-  onModelTranscript?: (transcript: ModelTranscript, meta: { phase: string; model: LlmModelRef }) => Promise<void>;
+  onModelTranscript?: (transcript: ModelTranscript, meta: { phase: string; model: ModelRef }) => Promise<void>;
   onMessage?: (message: AgentMessage) => Promise<void>;
   onOutcome?: (outcome: Outcome) => Promise<void>;
 };
 
-type AgentCreateOptions = AgentOptions & {
-  // Seeds the Session; it does not schedule a Run.
-  input?: string;
-  // Enables automatic reconstruction through a registered Factory.
-  factoryId?: string;
-};
+type AgentOptions = AgentCommonOptions & (
+  | { model: ModelConfig; stream?: never }
+  | { model: ModelRef; stream: StreamFn }
+);
 ```
 
 ### Conversation Continuation
@@ -214,6 +220,11 @@ console.log((await second.result()).message);
 If a Run is suspended waiting for input, the next `send()` to that Agent resumes
 the same Run instead of creating a second one.
 
+Suspended Runs persist the current input request in `AgentRunRecord.inputRequest`
+so a reconstructed Runtime can show the question without replaying a transient
+Agent Event. The request contains its phase, prompt, and timestamp; it is cleared
+when the Run resumes.
+
 ### Updating Runtime Resources
 
 Resources are fixed for a live Agent Binding. Apply a new model, prompt, Tool
@@ -228,8 +239,7 @@ await runtime.stop();
 const nextRuntime = await AgentRuntime.start({ stateStore, sessionProvider });
 const reconstructed = await nextRuntime.reconstructAgent(agentId, {
   context: currentContext,
-  model: { provider: "openai", id: "gpt-4.1" },
-  stream: createModelStream(),
+  model: currentModelConfig,
 });
 ```
 
@@ -240,18 +250,25 @@ durable. The handle exposes cached state for synchronous inspection and can
 refresh from the Runtime Store when needed.
 
 ```ts
+type AgentInputRequest = {
+  phase: string;
+  prompt: string;
+  requestedAt: string;
+};
+
 class AgentRun {
   readonly id: AgentRunId;
   readonly messageId: string;
   readonly status: AgentRunState;
   readonly state: AgentRunState; // alias of status
+  readonly inputRequest?: AgentInputRequest;
 
   getStatus(): Promise<AgentRunState>;
   subscribe(listener: AgentRunListener): () => void;
   consumeRuntimeEvents(
     consumerId: string,
     listener: (event: RuntimeEvent) => void | Promise<void>,
-  ): () => void;
+  ): RuntimeEventConsumer;
   result(): Promise<Outcome>;
   abort(reason?: string): Promise<void>;
 }
@@ -377,7 +394,7 @@ const runtime = await AgentRuntime.start({
   stateStore,
   sessionProvider,
   toolPolicy: {
-    allowedTools: ["read", "bash"],
+    allowedTools: ["read", "bash", "task_manage", "resource_manage"],
     maxConcurrent: 8,
     perToolMaxConcurrent: { bash: 2 },
   },
@@ -416,9 +433,58 @@ is asynchronous, so a slow or unavailable consumer does not block state
 transitions.
 
 ```ts
-const stopConsuming = runtime.consumeEvents("deployment-observer", async (event) => {
+const consumer = runtime.consumeEvents("deployment-observer", async (event) => {
   await deliverRuntimeFact(event);
 });
+await consumer.caughtUp;
+```
+
+Runtime Messages and their related Events are committed together. A durable
+consumer can use a `run_enqueued` Event as an outbox signal, read immutable
+business correlation metadata from its Message, and update an external index
+before its Checkpoint advances:
+
+```ts
+const indexConsumer = runtime.consumeEvents("everyield-run-index", async (event) => {
+  if (event.kind !== "run_enqueued" || !event.messageId || !event.runId) return;
+  const message = await runtime.getMessage(event.messageId);
+  if (!message) throw new Error(`Runtime Message not found: ${event.messageId}`);
+  await upsertRunIndex(event.runId, message.input.metadata);
+});
+await indexConsumer.caughtUp;
+```
+
+If the listener fails, Rowan leaves the Checkpoint unchanged and redelivers the
+Event after the consumer restarts. `getMessage()` is read-only; Rowan treats the
+Agent Message metadata as opaque host data.
+
+Tool Call Events can likewise be resolved to their durable record. This is
+especially useful when a `tool_call_indeterminate` Event requires host recovery
+or human review:
+
+```ts
+if (event.kind === "tool_call_indeterminate" && event.toolCallId) {
+  const toolCall = await runtime.getToolCall(event.toolCallId);
+  await reviewIndeterminateToolCall(toolCall);
+}
+```
+
+A consumer may instead return an `enqueue` disposition to turn the current
+Event into Agent Input. Rowan enqueues the input and advances the Consumer
+Checkpoint in one Runtime State transaction, then schedules the target Agent.
+
+```ts
+const routingConsumer = runtime.consumeEvents("delegated-results", (event) => {
+  if (event.kind !== "run_completed" || !event.agentId) return;
+  return {
+    type: "enqueue",
+    agentId: targetAgentId,
+    input: createMessage("user", JSON.stringify(event.payload), {
+      sourceEventId: event.id,
+    }),
+  };
+});
+await routingConsumer.caughtUp;
 ```
 
 Only one live subscription may use a Consumer ID. If delivery fails, its
@@ -427,6 +493,15 @@ started later. `runtime.listEvents()` inspects the durable stream without
 advancing a Consumer Checkpoint. Use `run.consumeRuntimeEvents()` for the same
 delivery contract filtered to one Run.
 
+`AgentRunMetadata` is optional opaque host data on `AgentMessage.metadata`. It
+is persisted with the Run and echoed on `run_enqueued`, suspension, completion,
+and abort Event payloads. `listActiveRuns()` returns queued, running, and
+suspended Runs for host-side Agent reconstruction with current `AgentOptions`.
+Use the returned `consumer.caughtUp` Promise when startup must wait until all
+Events through the durable Consumer checkpoint have been delivered before
+recovery continues. Call `consumer.stop()` during shutdown. `run.consumeRuntimeEvents()`
+returns the same handle shape.
+
 ### Parallel Phase Events
 
 When multiple phases run concurrently (via multi-target `route`), each branch emits its own `turn_*`, `message_*`, and `tool_execution_*` events into the shared event stream — they are interleaved, not sequenced. Individual parallel phases do **not** emit `phase_start`/`phase_end`; those only fire for serial phases. After all branches complete, their outputs are stashed and surfaced in the next iteration's phase entry message (under `<prev_phase_outputs>`); the `message_start`/`message_end` you observe for that entry message carry the merged results.
@@ -436,9 +511,9 @@ When multiple phases run concurrently (via multi-target `route`), each branch em
 JSONL-based session persistence — lets multi-turn conversations survive across process restarts. Supports create, resume, branch, and history replay.
 
 ```ts
-import { LocalJsonlSessionProvider } from "@rowan-agent/agent";
+import { JsonlSessionStore } from "@rowan-agent/agent";
 
-const sessions = new LocalJsonlSessionProvider(sessionsDir);
+const sessions = new JsonlSessionStore(sessionsDir);
 const session = await sessions.create({
   systemPrompt,
   input: "",
@@ -665,7 +740,7 @@ export default function myPlugin(rowan: ExtensionAPI) {
 
 ## Model Selection
 
-`AgentOptions` accepts a model reference and stream implementation from `@rowan-agent/models`. Phase frontmatter may override the model for that phase.
+`AgentOptions` accepts either one complete `ModelConfig`, which Rowan binds to an Agent-local default stream, or a model reference plus a custom `StreamFn`. A phase model override therefore requires a custom stream that can resolve the override.
 
 CLI-specific `.rowan/config.yaml` loading and workspace discovery belong to [`@rowan-agent/cli`](../cli/README.md).
 
@@ -691,6 +766,8 @@ type LoopMetrics = {
 | `AgentRun` | Durable Run handle for state, terminal Outcome, observation, and abort |
 | `SqliteRuntimeStateStore` / `InMemoryRuntimeStateStore` | Durable and test Runtime Store adapters |
 | `RuntimeEvent` / consumer ID string | Durable lifecycle facts and checkpointed consumer identity |
+| `RuntimeMessage` / `RuntimeMessageId` | Durable Agent Input and its stable lookup identity |
+| `RuntimeToolCall` / `RuntimeToolCallId` | Durable Tool Call state and its stable lookup identity |
 | `AgentContext` | System prompt, messages, tools, skills, phases |
 | `AgentMessage` | Typed message with role, content, metadata |
 | `AgentEvent` | Discriminated union of 13 event types |
@@ -702,9 +779,9 @@ type LoopMetrics = {
 | `Outcome` | Terminal result with message and tool results |
 | `LoopMetrics` | Loop iteration, timing, and phase transition stats |
 | `SessionManagerProvider` | Session lifecycle seam used by the Runtime |
-| `LocalJsonlSessionProvider` / `InMemorySessionProvider` | JSONL and in-memory Session adapters |
+| `JsonlSessionStore` / `InMemorySessionStore` | JSONL and in-memory Session adapters |
 | `ExtensionAPI` / `ExtensionFactory` | Extension developer interface |
-| `StreamFn` / `LlmModelRef` | Model stream function and model reference |
+| `StreamFn` / `ModelRef` | Model stream function and model reference |
 
 ## Documentation