@rowan-agent/agent 0.6.1 → 0.7.0

package/README.md

@@ -136,9 +136,9 @@ dead-lettered.
 
 ### Process Recovery
 
-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:
+Runtime startup and periodic recovery return expired Leases to durable queued
+work without disturbing unexpired Leases owned by another process. The host
+supplies its current executable resources when it reconstructs an Agent:
 
 ```ts
 const runtime = await AgentRuntime.start({ stateStore, sessionProvider });
@@ -337,17 +337,17 @@ const tools = createCoreTools({
   bashTimeoutMs?,      // default: 30s
   maxBashOutputBytes?, // default: 64KB
 });
-// Returns: read, write, edit, bash
+// Returns: read, bash, edit, write
 ```
 
 ### Built-in Tools
 
 | Tool | Description | Parameters |
 |------|-------------|------------|
-| `read` | Reads a text file within the workspace | `path` (required), `maxBytes?`, `type?` ("skill" \| "phase" \| "markdown" \| "code" \| "file") |
-| `write` | Writes content to a file, creating parent directories as needed | `path` (required), `content` (required) |
-| `edit` | Replaces exact `oldText` with `newText` in a file | `path` (required), `oldText` (required), `newText` (required), `replaceAll?` |
-| `bash` | Runs a bash command within the workspace | `command` (required), `cwd?`, `timeoutMs?`, `maxOutputBytes?` |
+| `read` | Reads a file, optionally by line range | `path` (required), `offset?`, `limit?` |
+| `bash` | Runs a bash command in the workspace | `command` (required), `timeout?` (seconds) |
+| `edit` | Applies exact replacements, including multiple disjoint edits in one call | `path` (required), `edits[]` (each with `oldText` and `newText`) |
+| `write` | Creates or overwrites a file | `path` (required), `content` (required) |
 
 ### Custom Tools
 
@@ -616,7 +616,7 @@ Two sources, merged by priority:
 
 ```yaml
 ---
-name: Code Review
+name: review
 description: Review code for correctness and style
 tools: [read, bash]
 target: execute
@@ -625,15 +625,14 @@ target: execute
 Review the current implementation for bugs and style issues.
 ```
 
-**Extension-registered** — via `api.registerPhase()`. Same id overrides file-based phases.
+**Extension-registered** — via `api.registerPhase()`. The phase name is used as its identity.
 
 ```ts
 import type { ExtensionAPI } from "@rowan-agent/agent";
 
 export default function myPlugin(api: ExtensionAPI) {
   api.registerPhase({
-    id: "review",
-    name: "Code Review",
+    name: "review",
     description: "Review code for correctness",
     tools: ["read", "bash"],
     async run(context, execution) {
@@ -648,8 +647,7 @@ export default function myPlugin(api: ExtensionAPI) {
 
 ```ts
 interface Phase {
-  id: string;
-  name: string;
+  name: string;                    // unique identity and display name
   description: string;
   tools?: string[];              // restrict tools (undefined = all)
   skills?: string[];             // restrict skills
@@ -674,7 +672,7 @@ interface PhaseContext {
 
 type PhaseOutput = {
   message: string;
-  route: string;                 // "continue" | "stop" | <phase-id>
+  route: string;                 // "continue" | "stop" | <phase-name>
   payload?: unknown;             // data passed to the next phase
 };
 ```
@@ -731,7 +729,7 @@ import type { ExtensionAPI } from "@rowan-agent/agent";
 export default function myPlugin(rowan: ExtensionAPI) {
   rowan.on("agent_start", (event) => { ... });
   rowan.registerTool({ name: "my_tool", description: "...", parameters: {...}, execute: async (args) => {...} });
-  rowan.registerPhase({ id: "review", description: "...", run: async (ctx) => {...} });
+  rowan.registerPhase({ name: "review", description: "...", run: async (ctx) => {...} });
   rowan.events.emit("my-plugin:ready", {});
 }
 ```
@@ -775,7 +773,7 @@ type LoopMetrics = {
 | `Skill` | Loaded skill bundle |
 | `Phase` | Phase definition with content, execution, and routing config |
 | `PhaseContext` / `PhaseOutput` | Phase input and output |
-| `PhaseRegistry` | Map of phase ids to Phase objects plus entry phase id |
+| `PhaseRegistry` | Map of phase names to Phase objects plus entry phase name |
 | `Outcome` | Terminal result with message and tool results |
 | `LoopMetrics` | Loop iteration, timing, and phase transition stats |
 | `SessionManagerProvider` | Session lifecycle seam used by the Runtime |

package/dist/index.d.ts

@@ -30,6 +30,7 @@ type RuntimeEventId = OpaqueId<"RuntimeEventId">;
 type LeaseId = OpaqueId<"LeaseId">;
 type RuntimeToolCallId = OpaqueId<"RuntimeToolCallId">;
 type AgentLifecycleState = "active" | "paused";
+type SessionLifecycleState = "active" | "archived" | "deleting";
 type RuntimeMessageState = "queued" | "leased" | "acknowledged" | "dead_lettered";
 type AgentRunState = "queued" | "running" | "suspended" | "completed" | "failed" | "cancelled";
 /** Opaque execution checkpoint owned by the Agent loop and persisted by Runtime. */
@@ -46,6 +47,8 @@ type AgentRecord = {
     id: AgentId;
     sessionId: string;
     state: AgentLifecycleState;
+    lifecycleState: SessionLifecycleState;
+    parentSessionId?: string;
     createdAt: string;
     updatedAt: string;
 };
@@ -84,7 +87,7 @@ type AgentRunRecord = {
     createdAt: string;
     updatedAt: string;
 };
-type RuntimeEventKind = "agent_created" | "agent_paused" | "agent_resumed" | "message_enqueued" | "run_enqueued" | "run_leased" | "lease_expired" | "lease_recovered" | "run_suspended" | "run_retry_scheduled" | "run_completed" | "run_aborted" | "message_acknowledged" | "message_dead_lettered" | "tool_call_created" | "tool_call_started" | "tool_call_failed" | "tool_call_completed" | "tool_call_indeterminate";
+type RuntimeEventKind = "agent_created" | "agent_paused" | "agent_resumed" | "session_archived" | "session_unarchived" | "message_enqueued" | "run_enqueued" | "run_leased" | "lease_expired" | "lease_recovered" | "run_suspended" | "run_retry_scheduled" | "run_completed" | "run_aborted" | "message_acknowledged" | "message_dead_lettered" | "tool_call_created" | "tool_call_started" | "tool_call_failed" | "tool_call_completed" | "tool_call_indeterminate";
 type RuntimeEvent = {
     id: RuntimeEventId;
     sequence: number;
@@ -325,9 +328,7 @@ interface PhaseContext {
  * Loaded Phase object
  */
 interface Phase {
-    /** Unique identifier */
-    id: string;
-    /** Display name */
+    /** Unique phase identity and display name. */
     name: string;
     /** Description */
     description: string;
@@ -358,9 +359,9 @@ interface Phase {
  * Phase registry containing all loaded phases
  */
 interface PhaseRegistry {
-    /** Map of phase id to Phase object */
+    /** Map of phase name to Phase object */
     phases: Map<string, Phase>;
-    /** Entry phase id (null until Agent applies its default phase) */
+    /** Entry phase name (null until Agent applies its default phase) */
     entryPhaseId: string | null;
 }
 
@@ -372,7 +373,6 @@ interface PhaseRegistry {
 type PhaseRun = (context: PhaseContext, execution: PhaseExecution) => Promise<PhaseOutput | void>;
 /** Phase definition shape used by extensions */
 type PhaseDefinition = {
-    id: string;
     name: string;
     description: string;
     run?: PhaseRun;
@@ -382,7 +382,7 @@ type PhaseDefinition = {
     input?: Record<string, string>;
     model?: string;
 };
-type PhaseRegistration = Partial<Omit<PhaseDefinition, 'run'>> & {
+type PhaseRegistration = Omit<PhaseDefinition, 'run'> & {
     /** Optional execution override — takes over model invocation */
     run?: PhaseRun;
 };
@@ -480,7 +480,6 @@ interface ExtensionManifest {
     entry?: string;
     name?: string;
     phase?: {
-        id?: string;
         name?: string;
         description?: string;
         tools?: string[];
@@ -603,7 +602,7 @@ interface EventBus {
  */
 interface BeforePhaseEvent {
     type: "before_phase";
-    /** Phase ID about to execute */
+    /** Phase name about to execute */
     phaseId: string;
     /** Phase input */
     input: PhaseContext;
@@ -617,7 +616,7 @@ interface BeforePhaseEvent {
  */
 interface AfterPhaseEvent {
     type: "after_phase";
-    /** Phase ID that completed */
+    /** Phase name that completed */
     phaseId: string;
     /** Phase output */
     output: PhaseOutput;
@@ -629,7 +628,7 @@ interface AfterPhaseEvent {
  */
 interface BeforePromptEvent {
     type: "before_prompt";
-    /** Current phase ID */
+    /** Current phase name */
     phaseId: string;
     /** Phase input (modifiable) */
     input: PhaseContext;
@@ -961,10 +960,10 @@ interface ExtensionContext {
     }>;
     /** Get skill content by name */
     getSkillContent?(skillName: string): string;
-    /** Get all available phase IDs */
+    /** Get all available phase names */
     getAvailablePhases?(): string[];
-    /** Get phase content by ID */
-    getPhaseContent?(phaseId: string): string;
+    /** Get phase content by name */
+    getPhaseContent?(phaseName: string): string;
 }
 /**
  * Utility functions available to extensions.
@@ -1033,10 +1032,10 @@ interface ExtensionAPI {
         setPayload(payload: unknown): void;
         /** Phase Out: set outcome message */
         setMessage(message: string): void;
-        /** Get current phase id */
+        /** Get current phase name */
         getCurrentPhase(): string;
         /** Set next phase (lower priority than PHASE.md target) */
-        setNextPhase(phaseId: string): void;
+        setNextPhase(phaseName: string): void;
         /** Get the next phase set by setNextPhase */
         getNextPhase(): string | undefined;
         /** Get the message set by setMessage */
@@ -1055,7 +1054,7 @@ type ExtensionFactory = (api: ExtensionAPI) => void | Promise<void>;
  * Scans for subdirectories containing PHASE.md files.
  * Returns PhaseRegistry with entryPhaseId:
  * - null by default (caller must explicitly set to start from a specific phase)
- * - Set to a specific phase id to start from that phase
+ * - Set to a specific phase name to start from that phase
  *
  * When entryPhaseId is null, Agent normalizes the registry to start from its default phase.
  */
@@ -1212,6 +1211,19 @@ declare const SkillSchema: Type.TObject<{
 }>;
 type Skill = Type.Static<typeof SkillSchema>;
 
+type SessionHeader = {
+    type: "header";
+    id: string;
+    version: string;
+    createdAt: string;
+    updatedAt: string;
+    systemPrompt: string;
+    input: string;
+    parentSessionId?: string;
+    skills: Skill[];
+    title?: string;
+    currentLeafId?: string | null;
+};
 type SessionAgentContext<TTool = unknown> = {
     systemPrompt: string;
     messages: AgentMessage[];
@@ -1241,6 +1253,7 @@ type SessionListItem = {
 };
 type SessionManager = {
     getSessionId(): string;
+    getHeader(): Promise<SessionHeader>;
     appendMessage(message: AgentMessage): Promise<string>;
     appendOutcome(outcome: Outcome): Promise<string>;
     appendModelTranscript(transcript: ModelTranscript, meta?: {
@@ -1252,10 +1265,13 @@ type SessionManager = {
 type SessionManagerProvider = {
     create(input: CreateSessionManagerInput): Promise<SessionManager>;
     open(sessionId: string): Promise<SessionManager | undefined>;
+    list(): Promise<SessionListItem[]>;
+    delete(sessionId: string): Promise<boolean>;
 };
 
 type CreateAgentInput = {
     sessionId: string;
+    parentSessionId?: string;
 };
 type EnqueueAgentInput = {
     agentId: AgentId;
@@ -1344,6 +1360,9 @@ interface RuntimeStateStore {
     getAgent(agentId: AgentId): Promise<AgentRecord | undefined>;
     listAgents(): Promise<AgentRecord[]>;
     setAgentState(agentId: AgentId, state: AgentLifecycleState): Promise<AgentRecord>;
+    setAgentLifecycleState(agentId: AgentId, state: SessionLifecycleState): Promise<AgentRecord>;
+    getAgentBySessionId(sessionId: string): Promise<AgentRecord | undefined>;
+    deleteAgentData(agentId: AgentId): Promise<void>;
     enqueueAgentInput(input: EnqueueAgentInput): Promise<EnqueuedAgentInput>;
     getMessage(messageId: RuntimeMessageId): Promise<RuntimeMessage | undefined>;
     getRun(runId: AgentRunId): Promise<AgentRunRecord | undefined>;
@@ -1399,6 +1418,17 @@ type RuntimeEventConsumer = {
     caughtUp: Promise<void>;
     stop(): void;
 };
+type RuntimeSessionSummary = {
+    id: string;
+    state: SessionLifecycleState;
+    createdAt: string;
+    updatedAt: string;
+    archivedAt?: string;
+    parentSessionId?: string;
+    agentId: AgentId;
+    activeRunCount: number;
+    title?: string;
+};
 declare class AgentRuntime {
     private readonly stateStore;
     private readonly sessionProvider?;
@@ -1409,6 +1439,7 @@ declare class AgentRuntime {
     private readonly toolRuntime;
     private readonly bindings;
     private readonly agents;
+    private readonly invalidatedAgents;
     private readonly runHandles;
     private readonly runWaiters;
     private readonly pendingRuns;
@@ -1420,6 +1451,7 @@ declare class AgentRuntime {
     private runningRuns;
     private pumping;
     private nextWorkerId;
+    private leaseRecoveryTimer;
     private stopped;
     private constructor();
     static start(options: AgentRuntimeOptions): Promise<AgentRuntime>;
@@ -1435,6 +1467,13 @@ declare class AgentRuntime {
     getRun(runId: AgentRunId): Promise<AgentRunRecord | undefined>;
     listActiveRuns(): Promise<AgentRunRecord[]>;
     listRuns(input?: ListRunsInput): Promise<AgentRunRecord[]>;
+    listSessions(input?: {
+        state?: SessionLifecycleState;
+    }): Promise<RuntimeSessionSummary[]>;
+    archiveSession(sessionId: string): Promise<void>;
+    unarchiveSession(sessionId: string): Promise<void>;
+    deleteSession(sessionId: string): Promise<void>;
+    private requireSessionAgent;
     getAgent(agentId: AgentId): Agent | undefined;
     getMessage(messageId: RuntimeMessageId): Promise<RuntimeMessage | undefined>;
     getToolCall(toolCallId: RuntimeToolCallId): Promise<RuntimeToolCall | undefined>;
@@ -1443,6 +1482,8 @@ declare class AgentRuntime {
     private registerEventConsumer;
     listEvents(cursor?: RuntimeEventCursor): Promise<RuntimeEvent[]>;
     private recover;
+    private startLeaseRecovery;
+    private recoverExpiredLeases;
     private scheduleQueuedRuns;
     private attachAgent;
     private submitAgentInput;
@@ -1534,6 +1575,14 @@ declare class InMemorySessionStore implements SessionManagerProvider {
     private readonly sessions;
     create(input: CreateSessionManagerInput): Promise<SessionManager>;
     open(sessionId: string): Promise<SessionManager | undefined>;
+    list(): Promise<{
+        id: string;
+        title: string | undefined;
+        createdAt: string;
+        updatedAt: string;
+        messageCount: any;
+    }[]>;
+    delete(sessionId: string): Promise<boolean>;
 }
 declare class JsonlSessionStore implements SessionManagerProvider {
     private readonly sessionsDir;
@@ -1541,6 +1590,7 @@ declare class JsonlSessionStore implements SessionManagerProvider {
     create(input: CreateSessionManagerInput): Promise<SessionManager>;
     open(sessionId: string): Promise<SessionManager | undefined>;
     list(): Promise<SessionListItem[]>;
+    delete(sessionId: string): Promise<boolean>;
 }
 
 type CoreToolContext = {
@@ -1560,8 +1610,11 @@ declare class InMemoryRuntimeStateStore implements RuntimeStateStore {
     private readonly eventCheckpoints;
     createAgent(input: CreateAgentInput): Promise<AgentRecord>;
     getAgent(agentId: AgentId): Promise<AgentRecord | undefined>;
+    getAgentBySessionId(sessionId: string): Promise<AgentRecord | undefined>;
     listAgents(): Promise<AgentRecord[]>;
     setAgentState(agentId: AgentId, state: AgentRecord["state"]): Promise<AgentRecord>;
+    setAgentLifecycleState(agentId: AgentId, state: AgentRecord["lifecycleState"]): Promise<AgentRecord>;
+    deleteAgentData(agentId: AgentId): Promise<void>;
     enqueueAgentInput(input: EnqueueAgentInput): Promise<EnqueuedAgentInput>;
     private enqueueAgentInputState;
     getMessage(messageId: RuntimeMessageId): Promise<RuntimeMessage | undefined>;
@@ -1600,8 +1653,11 @@ declare class SqliteRuntimeStateStore implements RuntimeStateStore {
     close(): void;
     createAgent(input: CreateAgentInput): Promise<AgentRecord>;
     getAgent(agentId: AgentId): Promise<AgentRecord | undefined>;
+    getAgentBySessionId(sessionId: string): Promise<AgentRecord | undefined>;
     listAgents(): Promise<AgentRecord[]>;
     setAgentState(agentId: AgentId, state: AgentRecord["state"]): Promise<AgentRecord>;
+    setAgentLifecycleState(agentId: AgentId, state: AgentRecord["lifecycleState"]): Promise<AgentRecord>;
+    deleteAgentData(agentId: AgentId): Promise<void>;
     enqueueAgentInput(input: EnqueueAgentInput): Promise<EnqueuedAgentInput>;
     private enqueueAgentInputState;
     getMessage(messageId: RuntimeMessageId): Promise<RuntimeMessage | undefined>;
@@ -1645,4 +1701,4 @@ declare class SqliteRuntimeStateStore implements RuntimeStateStore {
     private recordEventInternal;
 }
 
-export { type AfterToolCall, Agent, type AgentContext, type AgentId, type AgentInputRequest, type AgentOptions, AgentRun, type AgentRunExecutionState, type AgentRunId, type AgentRunListener, type AgentRunMetadata, type AgentRunRecord, type AgentRunState, AgentRuntime, type AgentRuntimeOptions, type BeforeToolCall, type CoreToolContext, type ExecutionTurn, type ExtensionAPI, type ExtensionFactory, type HookEvent, type HookEventType, type HookHandler, InMemoryRuntimeStateStore, InMemorySessionStore, JsonlSessionStore, type LoadExtensionsResult, type LoadedExtension, type LoopMetrics, type ModelTranscript, type Phase, type PhaseContext, type PhaseExecution, type PhaseInvocation, type PhaseOutput, type PhaseRegistration, type PhaseRegistry, type PhaseState, type RuntimeEvent, type RuntimeEventConsumer, type RuntimeEventCursor, type RuntimeEventDisposition, type RuntimeEventKind, type RuntimeEventListener, type RuntimeMessage, type RuntimeMessageId, type RuntimeToolCall, type RuntimeToolCallId, type SessionManagerProvider, SqliteRuntimeStateStore, type Tool, type ToolContext, type ToolDefinition, type ToolExecutionMode, type ToolExecutionResult, type ToolRuntimePolicy, type Unsubscribe, createCoreTools, createMessage };
+export { type AfterToolCall, Agent, type AgentContext, type AgentId, type AgentInputRequest, type AgentOptions, AgentRun, type AgentRunExecutionState, type AgentRunId, type AgentRunListener, type AgentRunMetadata, type AgentRunRecord, type AgentRunState, AgentRuntime, type AgentRuntimeOptions, type BeforeToolCall, type CoreToolContext, type ExecutionTurn, type ExtensionAPI, type ExtensionFactory, type HookEvent, type HookEventType, type HookHandler, InMemoryRuntimeStateStore, InMemorySessionStore, JsonlSessionStore, type LoadExtensionsResult, type LoadedExtension, type LoopMetrics, type ModelTranscript, type Phase, type PhaseContext, type PhaseExecution, type PhaseInvocation, type PhaseOutput, type PhaseRegistration, type PhaseRegistry, type PhaseState, type RuntimeEvent, type RuntimeEventConsumer, type RuntimeEventCursor, type RuntimeEventDisposition, type RuntimeEventKind, type RuntimeEventListener, type RuntimeMessage, type RuntimeMessageId, type RuntimeSessionSummary, type RuntimeToolCall, type RuntimeToolCallId, type SessionLifecycleState, type SessionManagerProvider, SqliteRuntimeStateStore, type Tool, type ToolContext, type ToolDefinition, type ToolExecutionMode, type ToolExecutionResult, type ToolRuntimePolicy, type Unsubscribe, createCoreTools, createMessage };