@rowan-agent/agent 0.6.1 → 0.7.0

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" })),
@@ -776,34 +854,27 @@ var DEFAULT_MAX_READ_BYTES = 64e3;
 var DEFAULT_BASH_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_BASH_OUTPUT_BYTES = 64e3;
 var ReadArgsSchema = Type2.Object({
-  path: Type2.String(),
-  maxBytes: Type2.Optional(Type2.Number()),
-  type: Type2.Optional(Type2.Union([
-    Type2.Literal("skill"),
-    Type2.Literal("phase"),
-    Type2.Literal("markdown"),
-    Type2.Literal("code"),
-    Type2.Literal("file")
-  ]))
+  path: Type2.String({ description: "Path to the file to read." }),
+  offset: Type2.Optional(Type2.Number({ description: "1-based line to start from." })),
+  limit: Type2.Optional(Type2.Number({ description: "Maximum number of lines." }))
 });
 var ReadArgsValidator = Schema.Compile(ReadArgsSchema);
 var WriteArgsSchema = Type2.Object({
-  path: Type2.String(),
-  content: Type2.String()
+  path: Type2.String({ description: "Path to the file to write." }),
+  content: Type2.String({ description: "Complete file contents." })
 });
 var WriteArgsValidator = Schema.Compile(WriteArgsSchema);
 var EditArgsSchema = Type2.Object({
-  path: Type2.String(),
-  oldText: Type2.String(),
-  newText: Type2.String(),
-  replaceAll: Type2.Optional(Type2.Boolean())
+  path: Type2.String({ description: "Path to the file to edit." }),
+  edits: Type2.Array(Type2.Object({
+    oldText: Type2.String({ description: "Exact unique text to replace." }),
+    newText: Type2.String({ description: "Replacement text." })
+  }), { description: "One or more non-overlapping replacements." })
 });
 var EditArgsValidator = Schema.Compile(EditArgsSchema);
 var BashArgsSchema = Type2.Object({
-  command: Type2.String(),
-  cwd: Type2.Optional(Type2.String()),
-  timeoutMs: Type2.Optional(Type2.Number()),
-  maxOutputBytes: Type2.Optional(Type2.Number())
+  command: Type2.String({ description: "Bash command to execute." }),
+  timeout: Type2.Optional(Type2.Number({ description: "Timeout in seconds." }))
 });
 var BashArgsValidator = Schema.Compile(BashArgsSchema);
 var validatorCache = /* @__PURE__ */ new WeakMap();
@@ -906,12 +977,7 @@ async function executeRuntimeToolCall(input) {
   }
   await input.observe?.({ type: "tool_start", tool, args });
   try {
-    const rawResult = await tool.execute(args, input.toolContext, input.signal);
-    let result = {
-      ...rawResult,
-      toolCallId: input.toolCall.id,
-      toolName: tool.name
-    };
+    let result = await tool.execute(args, input.toolContext, input.signal);
     if (input.afterToolCall) {
       await input.observe?.({
         type: "result_review_requested",
@@ -945,6 +1011,20 @@ function positiveNumber(value, name) {
   }
   return void 0;
 }
+function positiveInteger(value, name) {
+  if (!Number.isInteger(value) || value <= 0) {
+    return `${name} must be a positive integer.`;
+  }
+  return void 0;
+}
+function readTextLines(text, offset, limit) {
+  if (offset === void 0 && limit === void 0) {
+    return text;
+  }
+  const start = (offset ?? 1) - 1;
+  const lines = text.split(/\r\n|\n|\r/);
+  return lines.slice(start, limit === void 0 ? void 0 : start + limit).join("\n");
+}
 async function captureStream(stream, maxBytes) {
   const reader = stream.getReader();
   const chunks = [];
@@ -984,17 +1064,25 @@ async function captureStream(stream, maxBytes) {
 function createReadTool(context) {
   return {
     name: "read",
-    description: "Reads a text file within the workspace.",
+    description: "Read a file in the workspace.",
     parameters: ReadArgsSchema,
-    promptSnippet: "Read a text file (max 64KB default).",
-    promptGuidelines: [
-      "Always read a file before editing or writing to understand its current content.",
-      "Use maxBytes to limit output for large files."
-    ],
+    promptSnippet: "Read file contents.",
+    promptGuidelines: ["Read files before editing them."],
     async execute(args, toolContext) {
       const parsed = ReadArgsValidator.Parse(args);
+      const offsetError = parsed.offset === void 0 ? void 0 : positiveInteger(parsed.offset, "offset");
+      const limitError = parsed.limit === void 0 ? void 0 : positiveInteger(parsed.limit, "limit");
+      if (offsetError || limitError) {
+        return toolResult({
+          context: toolContext,
+          toolName: "read",
+          ok: false,
+          content: null,
+          error: offsetError ?? limitError
+        });
+      }
       const resolved = resolveCoreToolPath(context, parsed.path);
-      const maxBytes = parsed.maxBytes ?? context.maxReadBytes;
+      const maxBytes = context.maxReadBytes;
       const invalidLimit = positiveNumber(maxBytes, "maxBytes");
       if (invalidLimit) {
         return toolResult({
@@ -1016,9 +1104,12 @@ function createReadTool(context) {
         });
       }
       const bytes = await readFile2(resolved.absolutePath);
-      const sliced = bytes.subarray(0, maxBytes);
+      const source = new TextDecoder().decode(bytes);
+      const selected = readTextLines(source, parsed.offset, parsed.limit);
+      const selectedBytes = new TextEncoder().encode(selected);
+      const sliced = selectedBytes.subarray(0, maxBytes);
       const text = new TextDecoder().decode(sliced);
-      const resourceType = parsed.type ?? detectResourceType(resolved.absolutePath);
+      const resourceType = detectResourceType(resolved.absolutePath);
       let name;
       let baseDir;
       if (resourceType === "skill" || resourceType === "phase") {
@@ -1029,16 +1120,14 @@ function createReadTool(context) {
       } else {
         name = inferResourceName(resolved.absolutePath, basename2(resolved.absolutePath));
       }
+      const formatted = resourceType === "skill" || resourceType === "phase" ? formatResourceOutput({ type: resourceType, name, location: resolved.absolutePath, content: text, baseDir }) : text;
+      const content = selectedBytes.byteLength > maxBytes ? `${formatted}
+[truncated]` : formatted;
       return toolResult({
         context: toolContext,
         toolName: "read",
         ok: true,
-        content: {
-          path: resolved.relativePath,
-          content: formatResourceOutput({ type: resourceType, name, location: resolved.absolutePath, content: text, baseDir }),
-          sizeBytes: bytes.byteLength,
-          truncated: bytes.byteLength > maxBytes
-        }
+        content
       });
     }
   };
@@ -1046,13 +1135,10 @@ function createReadTool(context) {
 function createWriteTool(context) {
   return {
     name: "write",
-    description: "Writes provided text content to a workspace file, creating parent directories as needed.",
+    description: "Create or overwrite a file in the workspace.",
     parameters: WriteArgsSchema,
-    promptSnippet: "Write content to a file (creates parent dirs automatically).",
-    promptGuidelines: [
-      "Use write for new files or full file rewrites.",
-      "For partial edits, prefer the edit tool to avoid overwriting unchanged content."
-    ],
+    promptSnippet: "Create or overwrite files.",
+    promptGuidelines: ["Use edit for partial changes."],
     async execute(args, toolContext) {
       const parsed = WriteArgsValidator.Parse(args);
       const resolved = resolveCoreToolPath(context, parsed.path);
@@ -1062,69 +1148,74 @@ function createWriteTool(context) {
         context: toolContext,
         toolName: "write",
         ok: true,
-        content: {
-          path: resolved.relativePath,
-          bytesWritten: new TextEncoder().encode(parsed.content).byteLength
-        }
+        content: `Successfully wrote ${parsed.content.length} bytes to ${resolved.relativePath}.`
       });
     }
   };
 }
+function applyEditReplacements(current, edits) {
+  if (edits.length === 0) {
+    throw new Error("edits must contain at least one replacement.");
+  }
+  const matches = [];
+  for (const edit of edits) {
+    if (!edit.oldText) throw new Error("oldText must not be empty.");
+    const start = current.indexOf(edit.oldText);
+    if (start < 0) throw new Error(`oldText not found in file.`);
+    const second = current.indexOf(edit.oldText, start + edit.oldText.length);
+    if (second >= 0) {
+      const count = current.split(edit.oldText).length - 1;
+      throw new Error(`oldText appears ${count} times; provide more context.`);
+    }
+    matches.push({ start, end: start + edit.oldText.length, newText: edit.newText });
+  }
+  matches.sort((a, b) => a.start - b.start);
+  for (let index = 1; index < matches.length; index += 1) {
+    const previous = matches[index - 1];
+    const currentMatch = matches[index];
+    if (currentMatch.start < previous.end) {
+      throw new Error("edits must not overlap.");
+    }
+  }
+  let content = current;
+  for (let index = matches.length - 1; index >= 0; index -= 1) {
+    const match = matches[index];
+    content = content.slice(0, match.start) + match.newText + content.slice(match.end);
+  }
+  return { content, replacements: matches.length };
+}
 function createEditTool(context) {
   return {
     name: "edit",
-    description: "Edits a workspace text file by replacing exact oldText with newText.",
+    description: "Apply exact text replacements to a workspace file.",
     parameters: EditArgsSchema,
-    promptSnippet: "Replace exact text in a file (oldText \u2192 newText).",
-    promptGuidelines: [
-      "Read the file first to get the exact oldText to replace.",
-      "oldText must be an exact match including whitespace and indentation.",
-      "If oldText appears multiple times, set replaceAll=true or provide more surrounding context."
-    ],
+    promptSnippet: "Apply exact text replacements.",
+    promptGuidelines: ["Read the file first; each oldText must match exactly once."],
     async execute(args, toolContext) {
       const parsed = EditArgsValidator.Parse(args);
-      if (!parsed.oldText) {
-        return toolResult({
-          context: toolContext,
-          toolName: "edit",
-          ok: false,
-          content: null,
-          error: "oldText must not be empty."
-        });
-      }
       const resolved = resolveCoreToolPath(context, parsed.path);
       const current = await readFile2(resolved.absolutePath, "utf8");
-      if (!current.includes(parsed.oldText)) {
-        return toolResult({
-          context: toolContext,
-          toolName: "edit",
-          ok: false,
-          content: null,
-          error: `oldText not found in ${resolved.relativePath}.`
-        });
-      }
-      const matches = current.split(parsed.oldText).length - 1;
-      if (matches > 1 && !parsed.replaceAll) {
+      let next;
+      let replacements;
+      try {
+        const result = applyEditReplacements(current, parsed.edits);
+        next = result.content;
+        replacements = result.replacements;
+      } catch (error) {
         return toolResult({
           context: toolContext,
           toolName: "edit",
           ok: false,
           content: null,
-          error: `oldText appears ${matches} times in ${resolved.relativePath}; set replaceAll=true or provide more context.`
+          error: error instanceof Error ? error.message : String(error)
         });
       }
-      const replacements = parsed.replaceAll ? matches : 1;
-      const next = parsed.replaceAll ? current.split(parsed.oldText).join(parsed.newText) : current.replace(parsed.oldText, parsed.newText);
       await writeFile(resolved.absolutePath, next, "utf8");
       return toolResult({
         context: toolContext,
         toolName: "edit",
         ok: true,
-        content: {
-          path: resolved.relativePath,
-          replacements,
-          bytesWritten: new TextEncoder().encode(next).byteLength
-        }
+        content: `Successfully replaced ${replacements} block(s) in ${resolved.relativePath}.`
       });
     }
   };
@@ -1132,19 +1223,15 @@ function createEditTool(context) {
 function createBashTool(context) {
   return {
     name: "bash",
-    description: "Runs a bash command within the workspace.",
+    description: "Run a bash command in the workspace.",
     parameters: BashArgsSchema,
-    promptSnippet: "Execute a bash command (30s timeout, 64KB output limit).",
-    promptGuidelines: [
-      "Use bash for build commands, tests, git operations, and system tools.",
-      "Prefer dedicated tools (read/write/edit) for file operations.",
-      "Set timeoutMs for long-running commands."
-    ],
+    promptSnippet: "Run shell commands.",
+    promptGuidelines: ["Use read/write/edit for file operations."],
     async execute(args, toolContext, signal) {
       const parsed = BashArgsValidator.Parse(args);
-      const timeoutMs = parsed.timeoutMs ?? context.bashTimeoutMs;
-      const maxOutputBytes = parsed.maxOutputBytes ?? context.maxBashOutputBytes;
-      const invalidTimeout = positiveNumber(timeoutMs, "timeoutMs");
+      const timeoutMs = parsed.timeout === void 0 ? context.bashTimeoutMs : parsed.timeout * 1e3;
+      const maxOutputBytes = context.maxBashOutputBytes;
+      const invalidTimeout = positiveNumber(timeoutMs, "timeout");
       const invalidOutputLimit = positiveNumber(maxOutputBytes, "maxOutputBytes");
       if (invalidTimeout || invalidOutputLimit) {
         return toolResult({
@@ -1155,7 +1242,7 @@ function createBashTool(context) {
           error: invalidTimeout ?? invalidOutputLimit
         });
       }
-      const cwd = resolveCoreToolPath(context, parsed.cwd ?? ".");
+      const cwd = resolveCoreToolPath(context, ".");
       let timedOut = false;
       let aborted = false;
       const proc = Bun.spawn(["bash", "-lc", parsed.command], {
@@ -1182,19 +1269,14 @@ function createBashTool(context) {
           proc.exited
         ]);
         const ok = exitCode === 0 && !timedOut && !aborted;
+        const output = [stdout.text, stderr.text].filter(Boolean).join(stdout.text && stderr.text ? "\n" : "");
+        const content = stdout.truncated || stderr.truncated ? `${output}
+[truncated]` : output;
         return toolResult({
           context: toolContext,
           toolName: "bash",
           ok,
-          content: {
-            command: parsed.command,
-            cwd: cwd.relativePath,
-            exitCode,
-            stdout: stdout.text,
-            stderr: stderr.text,
-            stdoutTruncated: stdout.truncated,
-            stderrTruncated: stderr.truncated
-          },
+          content,
           ...ok ? {} : {
             error: timedOut ? `Command timed out after ${timeoutMs}ms.` : aborted ? "Command aborted." : `Command exited with ${exitCode}.`
           }
@@ -1210,9 +1292,9 @@ function createCoreTools(input = {}) {
   const context = createCoreToolContext(input);
   return [
     createReadTool(context),
-    createWriteTool(context),
+    createBashTool(context),
     createEditTool(context),
-    createBashTool(context)
+    createWriteTool(context)
   ];
 }
 
@@ -1403,6 +1485,23 @@ function removePhaseMessage(messages, msgId) {
   const idx = messages.findIndex((m) => m.id === msgId);
   if (idx !== -1) messages.splice(idx, 1);
 }
+function findLatestUserInputMessage(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    const kind = message.metadata?.kind;
+    if (message.role === "user" && kind !== "phase_prompt" && kind !== "phase_input") {
+      return message;
+    }
+  }
+  return void 0;
+}
+function moveMessageBefore(messages, messageId, targetId) {
+  const messageIndex = messages.findIndex((message2) => message2.id === messageId);
+  const targetIndex = messages.findIndex((message2) => message2.id === targetId);
+  if (messageIndex === -1 || targetIndex === -1 || messageIndex < targetIndex) return;
+  const [message] = messages.splice(messageIndex, 1);
+  if (message) messages.splice(targetIndex, 0, message);
+}
 function normalizePayload(payload) {
   if (typeof payload === "string") {
     try {
@@ -1423,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);
@@ -1539,6 +1638,15 @@ function createToolResultContent(result) {
     }
   ];
 }
+function createRouteToolResultContent(toolCall) {
+  return [
+    {
+      type: "tool_result",
+      toolUseId: toolCall.id,
+      content: '{"ok": true}'
+    }
+  ];
+}
 async function executePhaseWithModel(ctx) {
   const executableToolNames = new Set(
     ctx.context.tools.filter((tool) => tool.name !== PhaseRouteTool).map((tool) => tool.name)
@@ -1561,6 +1669,13 @@ async function executePhaseWithModel(ctx) {
       phase: ctx.phase.name,
       toolCalls: collected.toolCalls
     };
+    for (const toolCall of collected.toolCalls) {
+      if (toolCall.name !== PhaseRouteTool) continue;
+      const messageId = ctx.messageManager.start("tool", createRouteToolResultContent(toolCall), {
+        phase: ctx.phase.name
+      });
+      await ctx.messageManager.end(messageId);
+    }
     const executableToolCalls = collected.toolCalls.filter(
       (toolCall) => executableToolNames.has(toolCall.name)
     );
@@ -1570,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);
     }
@@ -1603,17 +1718,20 @@ async function runPhaseLoop(config, state, registry) {
   }
   let previousPayload = resumingSuspendedRun ? state.continuation?.previousPayload : void 0;
   let previousPhaseMsgId = resumingSuspendedRun ? state.continuation?.previousPhaseMessageId : void 0;
+  let previousPhaseInputMsgId;
   let previousResults = resumingSuspendedRun ? state.continuation?.previousResults?.map((result) => ({ ...result })) ?? [] : [];
   let pendingInstruction = resumingSuspendedRun ? state.continuation?.pendingInstruction : void 0;
   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") {
       removePhaseMessage(config.context.messages, previousPhaseMsgId);
+      removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
       previousPhaseMsgId = void 0;
+      previousPhaseInputMsgId = void 0;
       return completeRun(config, state, createOutcome.aborted());
     }
     state.metrics.iterations++;
@@ -1672,13 +1790,17 @@ async function runPhaseLoop(config, state, registry) {
       if (extBefore.abort) {
         config.emit?.({ type: "phase_end", phase: currentPhaseId, ts: createTimestamp() });
         removePhaseMessage(config.context.messages, previousPhaseMsgId);
+        removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
         previousPhaseMsgId = void 0;
+        previousPhaseInputMsgId = void 0;
         return completeRun(config, state, extBefore.abort);
       }
       if (extBefore.skip) {
         config.emit?.({ type: "phase_end", phase: currentPhaseId, ts: createTimestamp() });
         removePhaseMessage(config.context.messages, previousPhaseMsgId);
+        removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
         previousPhaseMsgId = void 0;
+        previousPhaseInputMsgId = void 0;
         if (extBefore.skip.route === "stop") {
           return completeRun(config, state, {
             id: "skip",
@@ -1696,13 +1818,32 @@ async function runPhaseLoop(config, state, registry) {
     if (enteringNewPhase || !phaseMessageIsPresent) {
       removePhaseMessage(config.context.messages, previousPhaseMsgId);
       removePhaseMessage(phaseContext.messages, previousPhaseMsgId);
+      removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
+      removePhaseMessage(phaseContext.messages, previousPhaseInputMsgId);
       previousPhaseMsgId = void 0;
+      previousPhaseInputMsgId = void 0;
+      const latestUserInputMessage = findLatestUserInputMessage(config.context.messages);
+      const lastMessageBeforePhase = config.context.messages.at(-1);
       previousPhaseMsgId = injectPhaseContent(
         phase,
         { results: previousResults, instruction: pendingInstruction },
         config.context.messages,
         phaseContext.messages
       );
+      if (previousPhaseMsgId) {
+        if (lastMessageBeforePhase?.role === "user") {
+          moveMessageBefore(config.context.messages, previousPhaseMsgId, lastMessageBeforePhase.id);
+          moveMessageBefore(phaseContext.messages, previousPhaseMsgId, lastMessageBeforePhase.id);
+        } else if (latestUserInputMessage) {
+          const phaseInputMessage = createMessage("user", latestUserInputMessage.content, {
+            kind: "phase_input",
+            phase: phase.name
+          });
+          config.context.messages.push(phaseInputMessage);
+          phaseContext.messages.push(phaseInputMessage);
+          previousPhaseInputMsgId = phaseInputMessage.id;
+        }
+      }
       previousResults = [];
       pendingInstruction = void 0;
     }
@@ -1720,7 +1861,9 @@ async function runPhaseLoop(config, state, registry) {
       if (extAfter.abort) {
         config.emit?.({ type: "phase_end", phase: currentPhaseId, ts: createTimestamp() });
         removePhaseMessage(config.context.messages, previousPhaseMsgId);
+        removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
         previousPhaseMsgId = void 0;
+        previousPhaseInputMsgId = void 0;
         return completeRun(config, state, extAfter.abort);
       }
       if (extAfter.retry && (phase.run || phase.factory)) {
@@ -1740,7 +1883,9 @@ async function runPhaseLoop(config, state, registry) {
         if (preAbort.stopReason !== "none") {
           config.emit?.({ type: "phase_end", phase: currentPhaseId, ts: createTimestamp() });
           removePhaseMessage(config.context.messages, previousPhaseMsgId);
+          removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
           previousPhaseMsgId = void 0;
+          previousPhaseInputMsgId = void 0;
           return completeRun(config, state, createOutcome.aborted());
         }
         const requestedAt = createTimestamp();
@@ -1768,7 +1913,9 @@ async function runPhaseLoop(config, state, registry) {
         if (abortResult2.stopReason !== "none") {
           config.emit?.({ type: "phase_end", phase: currentPhaseId, ts: createTimestamp() });
           removePhaseMessage(config.context.messages, previousPhaseMsgId);
+          removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
           previousPhaseMsgId = void 0;
+          previousPhaseInputMsgId = void 0;
           return completeRun(config, state, createOutcome.aborted());
         }
         for (const message of userMessages) {
@@ -1779,7 +1926,9 @@ async function runPhaseLoop(config, state, registry) {
       }
       config.emit?.({ type: "phase_end", phase: currentPhaseId, ts: createTimestamp() });
       removePhaseMessage(config.context.messages, previousPhaseMsgId);
+      removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
       previousPhaseMsgId = void 0;
+      previousPhaseInputMsgId = void 0;
       return completeRun(config, state, createOutcome.default(output, config.context.messages));
     }
     if (output.route === "continue") {
@@ -1822,7 +1971,9 @@ async function runPhaseLoop(config, state, registry) {
       const entryPhaseId = phase.target ?? registry.entryPhaseId;
       if (entryPhaseId === "stop") {
         removePhaseMessage(config.context.messages, previousPhaseMsgId);
+        removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
         previousPhaseMsgId = void 0;
+        previousPhaseInputMsgId = void 0;
         return completeRun(config, state, createTerminalOutcome(phase, output, config.context.messages));
       }
       currentPhaseId = entryPhaseId;
@@ -1839,13 +1990,17 @@ async function runPhaseLoop(config, state, registry) {
     }
     if (nextRoute === "stop") {
       removePhaseMessage(config.context.messages, previousPhaseMsgId);
+      removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
       previousPhaseMsgId = void 0;
+      previousPhaseInputMsgId = void 0;
       return completeRun(config, state, createTerminalOutcome(phase, output, config.context.messages));
     }
     const targetPhaseId = nextRoute;
     if (!registry.phases.has(targetPhaseId)) {
       removePhaseMessage(config.context.messages, previousPhaseMsgId);
+      removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
       previousPhaseMsgId = void 0;
+      previousPhaseInputMsgId = void 0;
       return completeRun(config, state, createOutcome.phaseNotFound(output));
     }
     state.metrics.phaseTransitions.push({
@@ -1854,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.");
@@ -1961,24 +2116,31 @@ async function executePhase(ctx) {
   return executePhaseWithModel(ctx);
 }
 async function executeToolCall(input) {
+  let result;
   if (input.config.runtime?.tools) {
-    return input.config.runtime.tools({
+    result = await input.config.runtime.tools({
       config: input.config,
       toolCall: input.toolCall
     });
+  } else {
+    const toolContext = {
+      skills: input.config.context.skills,
+      toolCallId: input.toolCall.id
+    };
+    result = await executeRuntimeToolCall({
+      tools: input.tools,
+      toolCall: input.toolCall,
+      toolContext,
+      beforeToolCall: input.config.beforeToolCall,
+      afterToolCall: input.config.afterToolCall,
+      signal: input.config.signal
+    });
   }
-  const toolContext = {
-    skills: input.config.context.skills,
-    toolCallId: input.toolCall.id
+  return {
+    ...result,
+    toolCallId: input.toolCall.id,
+    toolName: input.toolCall.name
   };
-  return executeRuntimeToolCall({
-    tools: input.tools,
-    toolCall: input.toolCall,
-    toolContext,
-    beforeToolCall: input.config.beforeToolCall,
-    afterToolCall: input.config.afterToolCall,
-    signal: input.config.signal
-  });
 }
 function createPhaseExecution(config, state, allTools, phase, messageManager, toolExecutionManager, registry) {
   return {
@@ -2000,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,
@@ -2027,7 +2189,7 @@ function createPhaseExecution(config, state, allTools, phase, messageManager, to
             config,
             message: messageManager,
             request,
-            phaseId: phase.id
+            phaseId: phase.name
           }),
           {
             signal: config.signal,
@@ -2049,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) {
@@ -2082,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
@@ -2101,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());
@@ -2189,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 = [];
@@ -2217,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);
     }
   }
@@ -2710,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);
   }
@@ -2723,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 };
@@ -2733,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,
@@ -3002,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 } : {}
     };
@@ -3025,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) {
@@ -3053,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;
@@ -4388,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) {
@@ -4403,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
@@ -4678,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 = [];
@@ -4689,6 +4908,7 @@ var AgentRuntime = class _AgentRuntime {
   runningRuns = 0;
   pumping = false;
   nextWorkerId = 0;
+  leaseRecoveryTimer;
   stopped = false;
   constructor(options) {
     this.stateStore = options.stateStore;
@@ -4723,7 +4943,17 @@ 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;
     } catch (error) {
       await runtime.stop().catch(() => void 0);
@@ -4740,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);
@@ -4753,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;
@@ -4766,6 +4999,10 @@ var AgentRuntime = class _AgentRuntime {
   async stop() {
     if (this.stopped) return;
     this.stopped = true;
+    if (this.leaseRecoveryTimer) {
+      clearInterval(this.leaseRecoveryTimer);
+      this.leaseRecoveryTimer = void 0;
+    }
     let suspendedAgents;
     try {
       suspendedAgents = new Set(
@@ -4857,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);
   }
@@ -4943,13 +5256,26 @@ var AgentRuntime = class _AgentRuntime {
     return this.stateStore.listEvents(cursor);
   }
   async recover() {
-    await this.stateStore.recoverLeases();
+    await this.recoverExpiredLeases();
     const agents = await this.stateStore.listAgents();
     for (const record of agents) {
       if (record.state === "paused") this.pausedAgents.add(record.id);
     }
     this.publishEvents();
   }
+  startLeaseRecovery() {
+    this.leaseRecoveryTimer = setInterval(() => {
+      void this.recoverExpiredLeases().catch(() => void 0);
+    }, this.leaseRenewalIntervalMs);
+  }
+  async recoverExpiredLeases() {
+    const recovered = await this.stateStore.recoverExpiredLeases();
+    for (const run of recovered) {
+      this.notifyRun(run);
+      if (this.bindings.has(run.agentId)) this.scheduleRun(run.agentId, run.id);
+    }
+    if (recovered.length > 0) this.publishEvents();
+  }
   async scheduleQueuedRuns(agentId) {
     if (!this.bindings.has(agentId)) return;
     const runs = await this.stateStore.listRuns({ agentId, states: ["queued"] });
@@ -4976,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);
@@ -5232,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
     };
@@ -5243,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()]);
   }
@@ -5255,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);
   }
@@ -5684,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
     );
@@ -5770,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(() => {
@@ -5786,6 +6150,7 @@ function initializeRuntimeSchema(database) {
     }
   });
   initialize();
+  database.run("INSERT OR IGNORE INTO runtime_schema (version) VALUES (2)");
 }
 
 // src/runtime/sqlite-store.ts
@@ -5829,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 });
     });
@@ -5846,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));
@@ -5861,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());
@@ -6350,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
     };