@rowan-agent/agent 0.6.2 → 0.7.0

package/README.md

@@ -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;
@@ -1436,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>;
@@ -1537,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;
@@ -1544,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 = {
@@ -1563,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>;
@@ -1603,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>;
@@ -1648,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 };

package/dist/index.js

@@ -387,51 +387,29 @@ import { dirname as dirname2, join, resolve } from "path";
 // src/harness/loader.ts
 import { readFile } from "fs/promises";
 import { basename, dirname, extname } from "path";
-function parseFrontmatter(raw) {
-  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
-  if (!match) return { frontmatter: {}, body: raw };
-  const lines = match[1].split("\n");
-  const frontmatter = {};
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const idx = line.indexOf(":");
-    if (idx === -1) continue;
-    const key = line.slice(0, idx).trim();
-    const value = line.slice(idx + 1).trim();
-    if (!key) continue;
-    if (value === "" && i + 1 < lines.length) {
-      const nested = {};
-      while (i + 1 < lines.length) {
-        const next = lines[i + 1];
-        if (!next.startsWith("  ") || next.trim() === "") break;
-        const nIdx = next.indexOf(":");
-        if (nIdx === -1) break;
-        const nKey = next.slice(0, nIdx).trim();
-        const nValue = next.slice(nIdx + 1).trim();
-        nested[nKey] = nValue;
-        i++;
-      }
-      if (Object.keys(nested).length) {
-        frontmatter[key] = nested;
-      }
-      continue;
-    }
-    frontmatter[key] = parseValue(value);
-  }
-  return { frontmatter, body: raw.slice(match[0].length) };
-}
-function parseValue(value) {
-  const arrayMatch = value.match(/^\[(.*)\]$/);
-  if (arrayMatch) {
-    return arrayMatch[1].split(",").map((s) => s.trim()).filter(Boolean);
+import { parse as parseYaml } from "yaml";
+var FrontmatterParseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FrontmatterParseError";
   }
-  if (value.toLowerCase() === "true") return true;
-  if (value.toLowerCase() === "false") return false;
-  if (/^\d+$/.test(value)) return Number(value);
-  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
-    return value.slice(1, -1);
+};
+function parseFrontmatter(raw) {
+  const normalized = raw.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (!normalized.startsWith("---")) return { frontmatter: {}, body: normalized };
+  const endIndex = normalized.indexOf("\n---", 3);
+  if (endIndex === -1) return { frontmatter: {}, body: normalized };
+  const yamlString = normalized.slice(4, endIndex);
+  try {
+    const frontmatter = parseYaml(yamlString) ?? {};
+    return {
+      frontmatter,
+      body: normalized.slice(endIndex + 4).trim()
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new FrontmatterParseError(message);
   }
-  return value;
 }
 async function loadMarkdown(filePath) {
   const raw = await readFile(filePath, "utf8");
@@ -543,6 +521,82 @@ function buildPhaseDirectiveMessage(phase, output) {
   return parts.join("\n");
 }
 
+// src/harness/resource-validation.ts
+var MAX_RESOURCE_ID_LENGTH = 64;
+var MAX_DESCRIPTION_LENGTH = 1024;
+var ResourceMetadataError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ResourceMetadataError";
+  }
+  code;
+};
+function validateResourceId(id, label = "id") {
+  const errors = [];
+  if (id.length > MAX_RESOURCE_ID_LENGTH) {
+    errors.push(`${label} exceeds ${MAX_RESOURCE_ID_LENGTH} characters (${id.length})`);
+  }
+  if (!/^[a-z0-9-]+$/.test(id)) {
+    errors.push(`${label} contains invalid characters (must be lowercase a-z, 0-9, hyphens only)`);
+  }
+  if (id.startsWith("-") || id.endsWith("-")) {
+    errors.push(`${label} must not start or end with a hyphen`);
+  }
+  if (id.includes("--")) {
+    errors.push(`${label} must not contain consecutive hyphens`);
+  }
+  return errors;
+}
+function validateResourceName(name, id) {
+  const errors = [];
+  if (name !== id) {
+    errors.push(`name "${name}" does not match parent directory "${id}"`);
+    errors.push(...validateResourceId(name, "name"));
+  }
+  return errors;
+}
+function validateDescription(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    return {
+      warnings: ["description is required"],
+      missing: true
+    };
+  }
+  if (value.length > MAX_DESCRIPTION_LENGTH) {
+    return {
+      description: value,
+      warnings: [`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${value.length})`],
+      missing: false
+    };
+  }
+  return { description: value, warnings: [], missing: false };
+}
+function validateSkillReferences(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) return ["skills must be an array"];
+  const errors = [];
+  for (const [index, skillId] of value.entries()) {
+    if (typeof skillId !== "string") {
+      errors.push(`skills[${index}] must be a string`);
+      continue;
+    }
+    errors.push(...validateResourceId(skillId, `skills[${index}]`));
+  }
+  return errors;
+}
+function validatePhaseTarget(value) {
+  if (value === void 0) return [];
+  if (typeof value !== "string") return ["target must be a string"];
+  if (value === "stop") return [];
+  return validateResourceId(value, "target");
+}
+function warnResourceDiagnostics(kind, filePath, diagnostics) {
+  for (const diagnostic of diagnostics) {
+    console.warn(`Invalid ${kind} metadata at "${filePath}": ${diagnostic}`);
+  }
+}
+
 // src/harness/phases/loader.ts
 var PHASE_MARKER = "PHASE.md";
 function resolvePhasePath(input) {
@@ -551,28 +605,44 @@ function resolvePhasePath(input) {
 }
 async function loadPhase(targetPath) {
   const resolved = resolvePhasePath(targetPath);
-  const { frontmatter, body } = await loadMarkdown(resolved);
-  const id = inferResourceName(resolved, PHASE_MARKER);
-  if (!frontmatter.name) {
-    throw new Error(`Phase "${id}" at "${resolved}" is missing required field "name" in PHASE.md frontmatter.`);
-  }
-  if (!frontmatter.description) {
-    throw new Error(`Phase "${id}" at "${resolved}" is missing required field "description" in PHASE.md frontmatter.`);
+  let loaded;
+  try {
+    loaded = await loadMarkdown(resolved);
+  } catch (error) {
+    if (!(error instanceof FrontmatterParseError)) throw error;
+    warnResourceDiagnostics("phase", resolved, [`frontmatter could not be parsed: ${error.message}`]);
+    throw new ResourceMetadataError("parse_failed", error.message);
+  }
+  const directoryName = inferResourceName(resolved, PHASE_MARKER);
+  const { frontmatter, body } = loaded;
+  const metadata = frontmatter;
+  const frontmatterName = typeof metadata.name === "string" ? metadata.name : void 0;
+  const name = frontmatterName || directoryName;
+  const description = validateDescription(metadata.description);
+  const diagnostics = validateResourceId(directoryName);
+  if (frontmatterName && frontmatterName !== directoryName) {
+    diagnostics.push(...validateResourceName(frontmatterName, directoryName));
+  }
+  diagnostics.push(...description.warnings);
+  diagnostics.push(...validateSkillReferences(metadata.skills));
+  diagnostics.push(...validatePhaseTarget(metadata.target));
+  warnResourceDiagnostics("phase", resolved, diagnostics);
+  if (description.missing) {
+    throw new ResourceMetadataError("invalid_metadata", "description is required");
   }
   const baseDir = dirname2(resolved);
   const phase = {
-    id,
-    name: frontmatter.name,
-    description: frontmatter.description,
-    tools: frontmatter.tools,
-    skills: frontmatter.skills,
-    target: frontmatter.target,
-    input: frontmatter.input,
-    isolated: frontmatter.isolated,
+    name,
+    description: description.description,
+    tools: metadata.tools,
+    skills: metadata.skills,
+    target: metadata.target,
+    input: metadata.input,
+    isolated: metadata.isolated,
     filePath: resolved,
     baseDir,
     content: body,
-    model: parseModelRef(frontmatter.model)
+    model: parseModelRef(metadata.model)
   };
   const codePath = await discoverPhaseCode(baseDir);
   if (codePath) {
@@ -598,13 +668,21 @@ async function loadPhases(targetPath) {
   const phases = /* @__PURE__ */ new Map();
   const phasesDir = resolve(targetPath);
   if (existsSync(phasesDir) && statSync(phasesDir).isFile()) {
-    const phase = await loadPhase(phasesDir);
-    phases.set(phase.id, phase);
+    try {
+      const phase = await loadPhase(phasesDir);
+      phases.set(phase.name, phase);
+    } catch (error) {
+      if (!(error instanceof ResourceMetadataError)) throw error;
+    }
     return { phases, entryPhaseId: null };
   }
   if (existsSync(join(phasesDir, PHASE_MARKER))) {
-    const phase = await loadPhase(phasesDir);
-    phases.set(phase.id, phase);
+    try {
+      const phase = await loadPhase(phasesDir);
+      phases.set(phase.name, phase);
+    } catch (error) {
+      if (!(error instanceof ResourceMetadataError)) throw error;
+    }
     return { phases, entryPhaseId: null };
   }
   const entries = await readdir(phasesDir, { withFileTypes: true });
@@ -614,8 +692,9 @@ async function loadPhases(targetPath) {
     if (!existsSync(phaseFile)) continue;
     try {
       const phase = await loadPhase(phaseFile);
-      phases.set(phase.id, phase);
+      phases.set(phase.name, phase);
     } catch (error) {
+      if (error instanceof ResourceMetadataError) continue;
       console.warn(`Failed to load phase "${entry.name}":`, error);
     }
   }
@@ -653,8 +732,7 @@ async function loadPhaseCode(codePath) {
 var DEFAULT_PHASE_ID = "default";
 function createDefaultPhase() {
   return {
-    id: DEFAULT_PHASE_ID,
-    name: "Execution Phase",
+    name: DEFAULT_PHASE_ID,
     description: "Executes concrete task operations and produces artifacts.",
     filePath: "",
     baseDir: "",
@@ -678,7 +756,7 @@ function normalizeRelativePath(path) {
 import Type from "typebox";
 var PhaseRouteTool = "route";
 function buildPhaseEntry(p) {
-  const entry = { id: p.id, description: p.description };
+  const entry = { name: p.name, description: p.description };
   if (p.tools && p.tools.length > 0) {
     entry.available_tools = p.tools.join(", ");
   }
@@ -693,7 +771,7 @@ function buildPhaseEntry(p) {
 function buildRouteDescription(availablePhases) {
   const phasesBlock = buildStructuredSection("phase", [
     ...availablePhases.map(buildPhaseEntry),
-    { id: "stop", description: "Terminate the workflow and return final result to the user" }
+    { name: "stop", description: "Terminate the workflow and return final result to the user" }
   ]);
   return [
     "Route execution to one or more phases concurrently, or stop execution.",
@@ -714,7 +792,7 @@ function buildRouteDescription(availablePhases) {
 function createRouteTool(availablePhases) {
   const DecisionTarget = Type.Object({
     phase: Type.Union([
-      ...availablePhases.map((p) => Type.Literal(p.id)),
+      ...availablePhases.map((p) => Type.Literal(p.name)),
       Type.Literal("stop")
     ]),
     reason: Type.Optional(Type.String({ description: "Brief reason for this decision" })),
@@ -1444,12 +1522,12 @@ function injectPhaseContent(phase, output, messages, mirror) {
   try {
     const phaseContent = phase.filePath ? readPhaseContent(phase) : phase.content ?? phase.description ?? "";
     const content = buildPhaseDirectiveMessage(
-      { name: phase.id, content: phaseContent },
+      { name: phase.name, content: phaseContent },
       output
     );
     const message = createMessage("user", content, {
       kind: "phase_prompt",
-      phase: phase.id
+      phase: phase.name
     });
     messages.push(message);
     if (mirror && mirror !== messages) mirror.push(message);
@@ -1594,7 +1672,7 @@ async function executePhaseWithModel(ctx) {
     for (const toolCall of collected.toolCalls) {
       if (toolCall.name !== PhaseRouteTool) continue;
       const messageId = ctx.messageManager.start("tool", createRouteToolResultContent(toolCall), {
-        phase: ctx.phase.id
+        phase: ctx.phase.name
       });
       await ctx.messageManager.end(messageId);
     }
@@ -1607,7 +1685,7 @@ async function executePhaseWithModel(ctx) {
     for (const toolCall of executableToolCalls) {
       const result = await ctx.execution.executeTool(roundContext, toolCall);
       const messageId = ctx.messageManager.start("tool", createToolResultContent(result), {
-        phase: ctx.phase.id
+        phase: ctx.phase.name
       });
       await ctx.messageManager.end(messageId);
     }
@@ -1646,7 +1724,7 @@ async function runPhaseLoop(config, state, registry) {
   while (currentPhaseId) {
     const availablePhases = [];
     for (const [, phase2] of registry.phases) {
-      availablePhases.push({ id: phase2.id, name: phase2.name, description: phase2.description, tools: phase2.tools, skills: phase2.skills, input: phase2.input, isolated: phase2.isolated });
+      availablePhases.push({ name: phase2.name, description: phase2.description, tools: phase2.tools, skills: phase2.skills, input: phase2.input, isolated: phase2.isolated });
     }
     const abortResult = LoopGuard.checkAbort(config.signal);
     if (abortResult.stopReason !== "none") {
@@ -1759,7 +1837,7 @@ async function runPhaseLoop(config, state, registry) {
         } else if (latestUserInputMessage) {
           const phaseInputMessage = createMessage("user", latestUserInputMessage.content, {
             kind: "phase_input",
-            phase: phase.id
+            phase: phase.name
           });
           config.context.messages.push(phaseInputMessage);
           phaseContext.messages.push(phaseInputMessage);
@@ -1931,7 +2009,7 @@ async function runPhaseLoop(config, state, registry) {
       ts: createTimestamp()
     });
     previousPayload = output.payload;
-    previousResults = output.payload !== void 0 ? [{ name: phase.id, output: output.payload }] : [];
+    previousResults = output.payload !== void 0 ? [{ name: phase.name, output: output.payload }] : [];
     currentPhaseId = targetPhaseId;
   }
   throw new Error("Phase machine exited without a stop or abort transition.");
@@ -2084,7 +2162,7 @@ function createPhaseExecution(config, state, allTools, phase, messageManager, to
     },
     async invokeModel(phaseContext) {
       if (config.beforePrompt) {
-        phaseContext = await config.beforePrompt(phase.id, phaseContext);
+        phaseContext = await config.beforePrompt(phase.name, phaseContext);
       }
       const request = buildModelRequest({
         systemPrompt: phaseContext.systemPrompt,
@@ -2111,7 +2189,7 @@ function createPhaseExecution(config, state, allTools, phase, messageManager, to
             config,
             message: messageManager,
             request,
-            phaseId: phase.id
+            phaseId: phase.name
           }),
           {
             signal: config.signal,
@@ -2133,7 +2211,7 @@ function createPhaseExecution(config, state, allTools, phase, messageManager, to
           }
         )
       );
-      await config.onModelTranscript?.(result.transcript, { phase: phase.id, model: phase.model ?? config.model });
+      await config.onModelTranscript?.(result.transcript, { phase: phase.name, model: phase.model ?? config.model });
       return result;
     },
     async executeTool(_context, toolCall) {
@@ -2166,7 +2244,7 @@ async function executeParallelPhase(config, state, registry, phase, payload, con
       sourcePhaseId
     },
     state: {
-      current: phase.id,
+      current: phase.name,
       available: Array.from(registry.phases.keys()),
       iterations: 0,
       payload
@@ -2185,7 +2263,7 @@ async function executeParallelPhase(config, state, registry, phase, payload, con
   if (phaseMsgId) removePhaseMessage(messages, phaseMsgId);
   const decision = output.toolCalls ? extractRouteCall(output.toolCalls) : void 0;
   const resultPayload = decision?.decision[0]?.payload !== void 0 ? normalizePayload(decision.decision[0].payload) : output.payload;
-  return { instanceId, phaseId: phase.id, payload: resultPayload, content: output.message };
+  return { instanceId, phaseId: phase.name, payload: resultPayload, content: output.message };
 }
 async function waitForBackgroundTasks(backgroundTasks) {
   const entries = Array.from(backgroundTasks.entries());
@@ -2273,23 +2351,55 @@ function readSkillContent(skill) {
 }
 async function loadSkill(path) {
   const resolved = resolveSkillPath(path);
-  const { frontmatter, body } = await loadMarkdown(resolved);
+  let loaded;
+  try {
+    loaded = await loadMarkdown(resolved);
+  } catch (error) {
+    if (!(error instanceof FrontmatterParseError)) throw error;
+    warnResourceDiagnostics("skill", resolved, [`frontmatter could not be parsed: ${error.message}`]);
+    throw new ResourceMetadataError("parse_failed", error.message);
+  }
+  const { frontmatter, body } = loaded;
+  const metadata = frontmatter;
+  const id = inferResourceName(resolved, SKILL_MARKER);
+  const frontmatterName = typeof metadata.name === "string" ? metadata.name : void 0;
+  const name = frontmatterName || id;
+  const description = validateDescription(metadata.description);
+  const diagnostics = validateResourceId(id);
+  if (frontmatterName && frontmatterName !== id) {
+    diagnostics.push(...validateResourceName(frontmatterName, id));
+  }
+  diagnostics.push(...description.warnings);
+  warnResourceDiagnostics("skill", resolved, diagnostics);
+  if (description.missing) {
+    throw new ResourceMetadataError("invalid_metadata", "description is required");
+  }
   return {
-    name: frontmatter.name ?? inferResourceName(resolved, SKILL_MARKER),
-    description: frontmatter.description ?? "",
+    name,
+    description: description.description,
     filePath: resolved,
     baseDir: dirname4(resolved),
     content: body,
-    disableModelInvocation: frontmatter["disable-model-invocation"] === true
+    disableModelInvocation: metadata["disable-model-invocation"] === true
   };
 }
 async function loadSkills(targetPath) {
   const skillsDir = resolve4(targetPath);
   if (existsSync2(skillsDir) && statSync2(skillsDir).isFile()) {
-    return [await loadSkill(skillsDir)];
+    try {
+      return [await loadSkill(skillsDir)];
+    } catch (error) {
+      if (error instanceof ResourceMetadataError) return [];
+      throw error;
+    }
   }
   if (existsSync2(join2(skillsDir, SKILL_MARKER))) {
-    return [await loadSkill(skillsDir)];
+    try {
+      return [await loadSkill(skillsDir)];
+    } catch (error) {
+      if (error instanceof ResourceMetadataError) return [];
+      throw error;
+    }
   }
   const entries = await readdir2(skillsDir, { withFileTypes: true });
   const skills = [];
@@ -2301,6 +2411,7 @@ async function loadSkills(targetPath) {
       const skill = await loadSkill(skillFile);
       skills.push(skill);
     } catch (error) {
+      if (error instanceof ResourceMetadataError) continue;
       console.warn(`Failed to load skill "${entry.name}":`, error);
     }
   }
@@ -2794,8 +2905,8 @@ var ExtensionRunner = class {
   // ---------------------------------------------------------------------------
   // Phase management
   // ---------------------------------------------------------------------------
-  getPhase(id) {
-    const reg = this.getRegisteredPhase(id);
+  getPhase(name) {
+    const reg = this.getRegisteredPhase(name);
     if (!reg) return void 0;
     return this.adaptToPhase(reg);
   }
@@ -2807,8 +2918,8 @@ var ExtensionRunner = class {
   createPhaseRegistry(input = {}) {
     const registered = this.collectRegisteredPhases();
     const phases = /* @__PURE__ */ new Map();
-    for (const [id, reg] of registered) {
-      phases.set(id, this.adaptToPhase(reg));
+    for (const [name, reg] of registered) {
+      phases.set(name, this.adaptToPhase(reg));
     }
     const entryPhaseId = input.entryPhaseId ?? null;
     return { phases, entryPhaseId };
@@ -2817,9 +2928,8 @@ var ExtensionRunner = class {
   adaptToPhase(reg) {
     const def = reg.definition;
     return {
-      id: def.id,
-      name: def.name ?? def.id,
-      description: def.description ?? "",
+      name: def.name,
+      description: def.description,
       tools: def.tools,
       skills: def.skills,
       target: def.target,
@@ -3086,22 +3196,27 @@ var ExtensionRunner = class {
     });
   }
   registerPhase(extension, registration) {
-    if (!registration.id) {
-      throw new Error(`Phase registration requires an "id" field.`);
-    }
-    if (!registration.name) {
-      throw new Error(`Phase registration "${registration.id}" requires a "name" field.`);
+    if (typeof registration.name !== "string" || registration.name.length === 0) {
+      throw new Error(`Phase registration requires a "name" field.`);
+    }
+    const name = registration.name;
+    const description = validateDescription(registration.description);
+    const errors = validateResourceId(name, "name");
+    if (description.missing) errors.push(...description.warnings);
+    errors.push(...validateSkillReferences(registration.skills));
+    errors.push(...validatePhaseTarget(registration.target));
+    if (errors.length > 0) {
+      throw new Error(`Invalid phase registration "${name}": ${errors.join("; ")}`);
     }
-    if (!registration.description) {
-      throw new Error(`Phase registration "${registration.id}" requires a "description" field.`);
+    if (description.warnings.length > 0) {
+      warnResourceDiagnostics("phase", `extension ${extension.path}`, description.warnings);
     }
-    if (this.phases.has(registration.id)) {
-      throw new Error(`Duplicate phase id: ${registration.id}`);
+    if (this.phases.has(name)) {
+      throw new Error(`Duplicate phase name: ${name}`);
     }
     const definition = {
-      id: registration.id,
-      name: registration.name,
-      description: registration.description,
+      name,
+      description: description.description,
       run: registration.run,
       ...registration.model ? { model: registration.model } : {}
     };
@@ -3109,8 +3224,8 @@ var ExtensionRunner = class {
       definition,
       source: { extensionPath: extension.path }
     };
-    this.phases.set(registration.id, registered);
-    extension.phases.set(registration.id, registered);
+    this.phases.set(name, registered);
+    extension.phases.set(name, registered);
     this._phaseCache = null;
   }
   registerProvider(config) {
@@ -3137,8 +3252,8 @@ var ExtensionRunner = class {
     }
     this.pendingProviders.length = 0;
   }
-  getRegisteredPhase(id) {
-    return this.collectRegisteredPhases().get(id);
+  getRegisteredPhase(name) {
+    return this.collectRegisteredPhases().get(name);
   }
   collectRegisteredPhases() {
     if (this._phaseCache) return this._phaseCache;
@@ -4472,6 +4587,22 @@ var InMemorySessionStore = class {
   async open(sessionId) {
     return this.sessions.get(sessionId);
   }
+  async list() {
+    return Promise.all([...this.sessions.values()].map(async (session) => {
+      const header = await session.getHeader();
+      const entries = "listEntries" in session && typeof session.listEntries === "function" ? await session.listEntries() : [];
+      return {
+        id: header.id,
+        title: header.title,
+        createdAt: header.createdAt,
+        updatedAt: header.updatedAt,
+        messageCount: entries.filter((entry) => entry.type === "message").length
+      };
+    }));
+  }
+  async delete(sessionId) {
+    return this.sessions.delete(sessionId);
+  }
 };
 var JsonlSessionStore = class {
   constructor(sessionsDir) {
@@ -4487,6 +4618,9 @@ var JsonlSessionStore = class {
   list() {
     return LocalJsonlSessionManager.list(this.sessionsDir);
   }
+  delete(sessionId) {
+    return LocalJsonlSessionManager.delete(this.sessionsDir, sessionId);
+  }
 };
 
 // src/runtime/agent-runtime.ts
@@ -4762,6 +4896,7 @@ var AgentRuntime = class _AgentRuntime {
   toolRuntime;
   bindings = /* @__PURE__ */ new Map();
   agents = /* @__PURE__ */ new Map();
+  invalidatedAgents = /* @__PURE__ */ new Set();
   runHandles = /* @__PURE__ */ new Map();
   runWaiters = /* @__PURE__ */ new Map();
   pendingRuns = [];
@@ -4808,6 +4943,15 @@ var AgentRuntime = class _AgentRuntime {
     const runtime = new _AgentRuntime(options);
     activeRuntime = runtime;
     try {
+      if (options.sessionProvider) {
+        for (const record of await options.stateStore.listAgents()) {
+          if (record.lifecycleState !== "deleting") continue;
+          const activeRuns = await options.stateStore.listRuns({ agentId: record.id, states: ["queued", "running", "suspended"] });
+          if (activeRuns.length > 0) continue;
+          await options.stateStore.deleteAgentData(record.id);
+          await options.sessionProvider.delete(record.sessionId);
+        }
+      }
       await runtime.recover();
       runtime.startLeaseRecovery();
       return runtime;
@@ -4826,8 +4970,10 @@ var AgentRuntime = class _AgentRuntime {
       input: "",
       skills: options.context.skills
     });
+    const header = await manager.getHeader();
     const record = await this.stateStore.createAgent({
-      sessionId: manager.getSessionId()
+      sessionId: manager.getSessionId(),
+      parentSessionId: header.parentSessionId
     });
     this.pausedAgents.delete(record.id);
     const agent = await this.attachAgent(record, manager, options);
@@ -4839,6 +4985,7 @@ var AgentRuntime = class _AgentRuntime {
     assertAgentOptions(options);
     const record = await this.stateStore.getAgent(agentId);
     if (!record) throw new Error(`Agent not found: ${agentId}.`);
+    if (record.lifecycleState !== "active") throw new Error(`Session ${record.sessionId} is ${record.lifecycleState}.`);
     if (record.state === "paused") this.pausedAgents.add(record.id);
     else this.pausedAgents.delete(record.id);
     const provider = this.sessionProvider;
@@ -4947,6 +5094,82 @@ var AgentRuntime = class _AgentRuntime {
   async listRuns(input) {
     return this.stateStore.listRuns(input);
   }
+  async listSessions(input = {}) {
+    const records = await this.stateStore.listAgents();
+    const items = this.sessionProvider ? await this.sessionProvider.list() : [];
+    const summaries = new Map(items.map((item) => [item.id, item]));
+    const activeRuns = await this.stateStore.listActiveRuns();
+    return records.filter((record) => !input.state || record.lifecycleState === input.state).map((record) => {
+      const item = summaries.get(record.sessionId);
+      return {
+        id: record.sessionId,
+        state: record.lifecycleState,
+        createdAt: record.createdAt,
+        updatedAt: item?.updatedAt ?? record.updatedAt,
+        ...record.lifecycleState === "archived" ? { archivedAt: record.updatedAt } : {},
+        ...record.parentSessionId ? { parentSessionId: record.parentSessionId } : {},
+        agentId: record.id,
+        activeRunCount: activeRuns.filter((run) => run.agentId === record.id).length,
+        ...item?.title ? { title: item.title } : {}
+      };
+    });
+  }
+  async archiveSession(sessionId) {
+    const record = await this.requireSessionAgent(sessionId);
+    if (record.lifecycleState === "archived") return;
+    if (record.lifecycleState === "deleting") throw new Error(`Session ${sessionId} is being deleted.`);
+    await this.stateStore.setAgentLifecycleState(record.id, "archived");
+    this.publishEvents();
+  }
+  async unarchiveSession(sessionId) {
+    const record = await this.requireSessionAgent(sessionId);
+    if (record.lifecycleState === "active") return;
+    if (record.lifecycleState === "deleting") throw new Error(`Session ${sessionId} is being deleted.`);
+    await this.stateStore.setAgentLifecycleState(record.id, "active");
+    await this.scheduleQueuedRuns(record.id);
+    this.publishEvents();
+  }
+  async deleteSession(sessionId) {
+    this.assertRunning();
+    if (!this.sessionProvider) throw new Error("Agent Runtime requires a SessionManager provider to delete a Session.");
+    if (!this.sessionProvider.delete) throw new Error("Session Manager provider does not support deletion.");
+    const root = await this.requireSessionAgent(sessionId);
+    const records = await this.stateStore.listAgents();
+    const subtree = /* @__PURE__ */ new Set([root.id]);
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const record of records) {
+        if (record.parentSessionId && records.some((candidate) => subtree.has(candidate.id) && candidate.sessionId === record.parentSessionId) && !subtree.has(record.id)) {
+          subtree.add(record.id);
+          changed = true;
+        }
+      }
+    }
+    const activeRuns = await this.stateStore.listActiveRuns();
+    if (activeRuns.some((run) => subtree.has(run.agentId))) {
+      throw new Error(`Session ${sessionId} has active Runs and cannot be deleted.`);
+    }
+    const targets = records.filter((record) => subtree.has(record.id));
+    for (const record of targets) await this.stateStore.setAgentLifecycleState(record.id, "deleting");
+    for (const record of targets) {
+      this.bindings.delete(record.id);
+      this.agents.delete(record.id);
+      this.invalidatedAgents.add(record.id);
+      this.pausedAgents.delete(record.id);
+      for (let index = this.pendingRuns.length - 1; index >= 0; index -= 1) {
+        if (this.pendingRuns[index]?.agentId === record.id) this.pendingRuns.splice(index, 1);
+      }
+      await this.stateStore.deleteAgentData(record.id);
+      await this.sessionProvider.delete(record.sessionId);
+    }
+    this.publishEvents();
+  }
+  async requireSessionAgent(sessionId) {
+    const record = await this.stateStore.getAgentBySessionId(sessionId);
+    if (!record) throw new Error(`Session not found: ${sessionId}.`);
+    return record;
+  }
   getAgent(agentId) {
     return this.agents.get(agentId);
   }
@@ -5079,7 +5302,11 @@ var AgentRuntime = class _AgentRuntime {
   }
   async submitAgentInput(agentId, input, persist) {
     this.assertRunning();
+    if (this.invalidatedAgents.has(agentId)) throw new Error(`Session for Agent ${agentId} was deleted.`);
     if (!this.bindings.has(agentId)) throw new Error(`Agent ${agentId} has no live Agent Binding.`);
+    const record = await this.stateStore.getAgent(agentId);
+    if (!record) throw new Error(`Agent ${agentId} was deleted.`);
+    if (record.lifecycleState !== "active") throw new Error(`Session ${record.sessionId} is ${record.lifecycleState}.`);
     const enqueued = await this.stateStore.enqueueAgentInput({ agentId, input });
     await persist();
     if (enqueued.resumed) this.notifyRun(enqueued.run);
@@ -5335,6 +5562,8 @@ var InMemoryRuntimeStateStore = class {
       id: createId("agt"),
       sessionId: input.sessionId,
       state: "active",
+      lifecycleState: "active",
+      ...input.parentSessionId ? { parentSessionId: input.parentSessionId } : {},
       createdAt: timestamp,
       updatedAt: timestamp
     };
@@ -5346,6 +5575,10 @@ var InMemoryRuntimeStateStore = class {
     const agent = this.agents.get(agentId);
     return agent ? clone2(agent) : void 0;
   }
+  async getAgentBySessionId(sessionId) {
+    const agent = [...this.agents.values()].find((candidate) => candidate.sessionId === sessionId);
+    return agent ? clone2(agent) : void 0;
+  }
   async listAgents() {
     return clone2([...this.agents.values()]);
   }
@@ -5358,6 +5591,27 @@ var InMemoryRuntimeStateStore = class {
     this.recordEvent(state === "paused" ? "agent_paused" : "agent_resumed", { agentId });
     return clone2(agent);
   }
+  async setAgentLifecycleState(agentId, state) {
+    const agent = this.requireAgent(agentId);
+    if (agent.lifecycleState === state) return clone2(agent);
+    agent.lifecycleState = state;
+    agent.updatedAt = createTimestamp();
+    if (state === "archived") this.recordEvent("session_archived", { agentId });
+    if (state === "active") this.recordEvent("session_unarchived", { agentId });
+    return clone2(agent);
+  }
+  async deleteAgentData(agentId) {
+    this.requireAgent(agentId);
+    const runIds = new Set([...this.runs.values()].filter((run) => run.agentId === agentId).map((run) => run.id));
+    for (const [id, call] of this.toolCalls) if (call.agentId === agentId || runIds.has(call.runId)) this.toolCalls.delete(id);
+    for (const [id, run] of this.runs) if (run.agentId === agentId) this.runs.delete(id);
+    for (const [id, message] of this.messages) if (message.agentId === agentId) this.messages.delete(id);
+    for (let index = this.events.length - 1; index >= 0; index -= 1) {
+      const event = this.events[index];
+      if (event?.agentId === agentId || event?.runId && runIds.has(event.runId)) this.events.splice(index, 1);
+    }
+    this.agents.delete(agentId);
+  }
   async enqueueAgentInput(input) {
     return this.enqueueAgentInputState(input);
   }
@@ -5787,10 +6041,15 @@ import { Database } from "bun:sqlite";
 
 // src/runtime/runtime-schema.ts
 var RUNTIME_SCHEMA_SQL = `
+    CREATE TABLE IF NOT EXISTS runtime_schema (
+      version INTEGER PRIMARY KEY NOT NULL
+    );
     CREATE TABLE IF NOT EXISTS agents (
       id TEXT PRIMARY KEY NOT NULL,
       session_id TEXT NOT NULL,
+      parent_session_id TEXT,
       state TEXT NOT NULL CHECK (state IN ('active', 'paused')),
+      lifecycle_state TEXT NOT NULL CHECK (lifecycle_state IN ('active', 'archived', 'deleting')),
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );
@@ -5873,6 +6132,8 @@ var RUNTIME_SCHEMA_SQL = `
 
     CREATE INDEX IF NOT EXISTS agent_runs_runnable_idx
       ON agent_runs (state, created_at);
+    CREATE UNIQUE INDEX IF NOT EXISTS agents_session_id_unique
+      ON agents (session_id);
 `;
 function initializeRuntimeSchema(database) {
   const initialize = database.transaction(() => {
@@ -5889,6 +6150,7 @@ function initializeRuntimeSchema(database) {
     }
   });
   initialize();
+  database.run("INSERT OR IGNORE INTO runtime_schema (version) VALUES (2)");
 }
 
 // src/runtime/sqlite-store.ts
@@ -5932,13 +6194,15 @@ var SqliteRuntimeStateStore = class {
       id: createId("agt"),
       sessionId: input.sessionId,
       state: "active",
+      lifecycleState: "active",
+      ...input.parentSessionId ? { parentSessionId: input.parentSessionId } : {},
       createdAt: timestamp,
       updatedAt: timestamp
     };
     const create = this.database.transaction(() => {
       this.database.run(
-        "INSERT INTO agents (id, session_id, state, created_at, updated_at) VALUES (?, ?, ?, ?, ?)",
-        [agent.id, agent.sessionId, agent.state, agent.createdAt, agent.updatedAt]
+        "INSERT INTO agents (id, session_id, parent_session_id, state, lifecycle_state, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+        [agent.id, agent.sessionId, agent.parentSessionId ?? null, agent.state, agent.lifecycleState, agent.createdAt, agent.updatedAt]
       );
       this.recordEvent("agent_created", { agentId: agent.id });
     });
@@ -5949,6 +6213,10 @@ var SqliteRuntimeStateStore = class {
     const row = this.database.query("SELECT * FROM agents WHERE id = ?").get(agentId);
     return row ? this.agentFromRow(row) : void 0;
   }
+  async getAgentBySessionId(sessionId) {
+    const row = this.database.query("SELECT * FROM agents WHERE session_id = ?").get(sessionId);
+    return row ? this.agentFromRow(row) : void 0;
+  }
   async listAgents() {
     const rows = this.database.query("SELECT * FROM agents ORDER BY created_at, id").all();
     return rows.map((row) => this.agentFromRow(row));
@@ -5964,6 +6232,34 @@ var SqliteRuntimeStateStore = class {
     })();
     return clone3(updated);
   }
+  async setAgentLifecycleState(agentId, state) {
+    const current = this.requireAgent(agentId);
+    if (current.lifecycleState === state) return clone3(current);
+    const { timestamp } = timestampFor();
+    const updated = this.database.transaction(() => {
+      this.database.run("UPDATE agents SET lifecycle_state = ?, updated_at = ? WHERE id = ?", [state, timestamp, agentId]);
+      if (state === "archived") this.recordEvent("session_archived", { agentId });
+      if (state === "active" && current.lifecycleState === "archived") this.recordEvent("session_unarchived", { agentId });
+      return this.requireAgent(agentId);
+    })();
+    return clone3(updated);
+  }
+  async deleteAgentData(agentId) {
+    this.database.transaction(() => {
+      const agent = this.requireAgent(agentId);
+      const runIds = this.database.query("SELECT id FROM agent_runs WHERE agent_id = ?").all(agentId).map((row) => row.id);
+      if (runIds.length > 0) {
+        const marks = runIds.map(() => "?").join(",");
+        this.database.run(`DELETE FROM runtime_tool_calls WHERE run_id IN (${marks})`, runIds);
+        this.database.run(`DELETE FROM runtime_leases WHERE run_id IN (${marks})`, runIds);
+        this.database.run(`DELETE FROM runtime_events WHERE agent_id = ? OR run_id IN (${marks})`, [agentId, ...runIds]);
+        this.database.run(`DELETE FROM agent_runs WHERE id IN (${marks})`, runIds);
+      }
+      this.database.run("DELETE FROM runtime_messages WHERE agent_id = ?", [agentId]);
+      this.database.run("DELETE FROM runtime_events WHERE agent_id = ?", [agentId]);
+      this.database.run("DELETE FROM agents WHERE id = ?", [agentId]);
+    })();
+  }
   async enqueueAgentInput(input) {
     const enqueue = this.database.transaction(() => this.enqueueAgentInputState(input));
     return clone3(enqueue());
@@ -6453,6 +6749,8 @@ var SqliteRuntimeStateStore = class {
       id: row.id,
       sessionId: row.session_id,
       state: row.state,
+      lifecycleState: row.lifecycle_state,
+      ...row.parent_session_id ? { parentSessionId: row.parent_session_id } : {},
       createdAt: row.created_at,
       updatedAt: row.updated_at
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowan-agent/agent",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,7 +25,8 @@
   "dependencies": {
     "@rowan-agent/models": "0.6.2",
     "jiti": "2.7.0",
-    "typebox": "^1.0.0"
+    "typebox": "^1.0.0",
+    "yaml": "^2.7.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1"