killeros 1.5.2 → 1.5.4

package/killeros/subagent-lifecycle.ts

@@ -3,8 +3,8 @@
 declare const threadIdBrand: unique symbol;
 
 export type SubagentThreadId = string & { readonly [threadIdBrand]: "SubagentThreadId" };
-export type SubagentThreadState = "queued" | "active" | "done" | "failed" | "stopped" | "closed";
-export type SubagentTerminalState = Extract<SubagentThreadState, "done" | "failed" | "stopped">;
+export type SubagentThreadState = "queued" | "active" | "done" | "failed" | "stopped" | "orphaned" | "closed";
+export type SubagentTerminalState = Extract<SubagentThreadState, "done" | "failed" | "stopped" | "orphaned">;
 export type SubagentFilesystemAccess = "none" | "read" | "write";
 export type SubagentNetworkAccess = "none" | "read" | "full";
 export type SubagentProcessAccess = "none" | "limited" | "full";
@@ -59,13 +59,20 @@ export interface SubagentThreadTimestamps {
   closedAt?: number;
 }
 
+export interface SubagentThreadSession {
+  id: string;
+  directory: string;
+}
+
 export interface SubagentThreadSpec {
   parentId?: SubagentThreadId;
+  displayName: string;
   role: string;
   prompt: string;
   model: string;
   tools: readonly string[];
   capabilityBoundary: SubagentCapabilityBoundary;
+  session: SubagentThreadSession;
   handoff?: SubagentHandoff;
 }
 
@@ -90,6 +97,7 @@ export interface SubagentStop extends SubagentThreadPatch {
 
 export interface SubagentThread extends SubagentThreadSpec {
   id: SubagentThreadId;
+  attempt: number;
   state: SubagentThreadState;
   usage: SubagentUsage;
   trace: SubagentTraceEvent[];
@@ -113,6 +121,7 @@ export type SubagentThreadChangeType =
   | "fail"
   | "stop"
   | "interrupt"
+  | "resume"
   | "close";
 
 export interface SubagentThreadChange {
@@ -129,10 +138,21 @@ export interface SubagentThreadRegistryOptions {
 
 export type SubagentThreadListener = (change: SubagentThreadChange) => void;
 
+export interface SubagentWaitResult {
+  threadIds: readonly SubagentThreadId[];
+  completedThreadIds: readonly SubagentThreadId[];
+  pendingThreadIds: readonly SubagentThreadId[];
+  timedOut: boolean;
+  waitedMs: number;
+  threads: readonly SubagentThread[];
+}
+
 const DEFAULT_MAX_STEERING_MESSAGES = 20;
 const DEFAULT_MAX_STEERING_MESSAGE_LENGTH = 4_000;
 const UPDATABLE_STATES = new Set<SubagentThreadState>(["queued", "active"]);
-const TERMINAL_STATES = new Set<SubagentThreadState>(["done", "failed", "stopped"]);
+const TERMINAL_STATES = new Set<SubagentThreadState>(["done", "failed", "stopped", "orphaned"]);
+const DISPLAY_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._ -]{0,47}$/u;
+const MAX_WAIT_TIMEOUT_MS = 2_147_483_647;
 const USAGE_FIELDS = [
   "inputTokens",
   "outputTokens",
@@ -168,6 +188,10 @@ function copyBoundary(boundary: SubagentCapabilityBoundary): SubagentCapabilityB
   return { ...boundary };
 }
 
+function copySession(session: SubagentThreadSession): SubagentThreadSession {
+  return { id: session.id, directory: session.directory };
+}
+
 function copyTraceEvent(event: SubagentTraceEvent): SubagentTraceEvent {
   return {
     at: event.at,
@@ -181,12 +205,15 @@ function snapshot(thread: SubagentThread): SubagentThread {
   return {
     id: thread.id,
     parentId: thread.parentId,
+    displayName: thread.displayName,
     role: thread.role,
     prompt: thread.prompt,
     model: thread.model,
     tools: [...thread.tools],
     capabilityBoundary: copyBoundary(thread.capabilityBoundary),
+    session: copySession(thread.session),
     handoff: copyHandoff(thread.handoff),
+    attempt: thread.attempt,
     state: thread.state,
     usage: { ...thread.usage },
     trace: thread.trace.map(copyTraceEvent),
@@ -201,7 +228,7 @@ function snapshot(thread: SubagentThread): SubagentThread {
 }
 
 function requireText(value: string, name: string): void {
-  if (!value.trim()) throw new Error(`${name} must be non-empty`);
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} must be non-empty`);
 }
 
 function requirePositiveInteger(value: number, name: string): void {
@@ -218,12 +245,27 @@ function validateUsage(patch: Partial<SubagentUsage>): void {
 }
 
 function validateHandoff(handoff: SubagentHandoff): void {
+  if (!handoff || typeof handoff !== "object") throw new Error("handoff must be an object");
   requireText(handoff.summary, "handoff.summary");
   if (handoff.nextAction !== undefined) requireText(handoff.nextAction, "handoff.nextAction");
+  if (handoff.artifacts !== undefined && !Array.isArray(handoff.artifacts)) throw new Error("handoff.artifacts must be an array");
   for (const artifact of handoff.artifacts ?? []) requireText(artifact, "handoff artifact");
 }
 
+function validateDisplayName(displayName: string): void {
+  if (typeof displayName !== "string" || !DISPLAY_NAME_PATTERN.test(displayName)) {
+    throw new Error("display name must match ^[A-Za-z0-9][A-Za-z0-9._ -]{0,47}$");
+  }
+}
+
+function validateSession(session: SubagentThreadSession): void {
+  if (!session || typeof session !== "object") throw new Error("session must be an object");
+  requireText(session.id, "session.id");
+  requireText(session.directory, "session.directory");
+}
+
 function validateBoundary(boundary: SubagentCapabilityBoundary): void {
+  if (!boundary || typeof boundary !== "object") throw new Error("capabilityBoundary must be an object");
   if (!(["none", "read", "write"] as string[]).includes(boundary.filesystem)) {
     throw new Error("capabilityBoundary.filesystem must be none, read, or write");
   }
@@ -236,10 +278,56 @@ function validateBoundary(boundary: SubagentCapabilityBoundary): void {
   if (typeof boundary.childThreads !== "boolean") throw new Error("capabilityBoundary.childThreads must be a boolean");
 }
 
+function validateTraceDetails(details: Readonly<Record<string, string | number | boolean | null>> | undefined): void {
+  if (details === undefined) return;
+  if (!details || typeof details !== "object" || Array.isArray(details)) throw new Error("trace.details must be an object");
+  for (const value of Object.values(details)) {
+    if (value !== null && !["string", "number", "boolean"].includes(typeof value)) {
+      throw new Error("trace.details values must be strings, numbers, booleans, or null");
+    }
+  }
+}
+
+function validateTraceEvent(event: SubagentTraceEvent, index: number): void {
+  if (!event || typeof event !== "object") throw new Error(`trace[${index}] must be an object`);
+  if (!Number.isFinite(event.at)) throw new Error(`trace[${index}].at must be a finite number`);
+  requireText(event.kind, `trace[${index}].kind`);
+  if (event.message !== undefined) requireText(event.message, `trace[${index}].message`);
+  validateTraceDetails(event.details);
+}
+
+function validateSteeringMessage(message: SubagentSteeringMessage, index: number): void {
+  if (!message || typeof message !== "object") throw new Error(`steering[${index}] must be an object`);
+  requirePositiveInteger(message.id, `steering[${index}].id`);
+  if (!Number.isFinite(message.at)) throw new Error(`steering[${index}].at must be a finite number`);
+  requireText(message.message, `steering[${index}].message`);
+}
+
+function validateCompleteUsage(usage: SubagentUsage): void {
+  if (!usage || typeof usage !== "object") throw new Error("usage must be an object");
+  for (const field of USAGE_FIELDS) {
+    if (!(field in usage)) throw new Error(`usage.${field} is required`);
+  }
+  validateUsage(usage);
+}
+
+function validateTimestamps(timestamps: SubagentThreadTimestamps): void {
+  if (!timestamps || typeof timestamps !== "object") throw new Error("timestamps must be an object");
+  for (const field of ["createdAt", "updatedAt", "startedAt", "endedAt", "closedAt"] as const) {
+    const value = timestamps[field];
+    if (value !== undefined && !Number.isFinite(value)) throw new Error(`timestamps.${field} must be a finite number`);
+  }
+  if (timestamps.createdAt === undefined) throw new Error("timestamps.createdAt is required");
+  if (timestamps.updatedAt === undefined) throw new Error("timestamps.updatedAt is required");
+}
+
 function isTerminal(state: SubagentThreadState): state is SubagentTerminalState {
   return TERMINAL_STATES.has(state);
 }
 
+// Module-scoped so fresh registries keep assigning fresh ids across session replacements.
+let nextId = 0;
+
 /**
  * Owns child-thread state only. Callers execute, cancel, and transport work.
  * Each read returns a copy, so callers cannot mutate registry state.
@@ -251,7 +339,6 @@ export class SubagentThreadRegistry {
   private readonly createId: () => string;
   private readonly maxSteeringMessages: number;
   private readonly maxSteeringMessageLength: number;
-  private nextId = 0;
   private nextSteeringId = 0;
   private disposed = false;
 
@@ -261,7 +348,7 @@ export class SubagentThreadRegistry {
     this.maxSteeringMessageLength = options.maxSteeringMessageLength ?? DEFAULT_MAX_STEERING_MESSAGE_LENGTH;
     requirePositiveInteger(this.maxSteeringMessages, "maxSteeringMessages");
     requirePositiveInteger(this.maxSteeringMessageLength, "maxSteeringMessageLength");
-    this.createId = options.createId ?? (() => `subagent-${++this.nextId}`);
+    this.createId = options.createId ?? (() => `subagent-${++nextId}`);
   }
 
   get isDisposed(): boolean {
@@ -271,6 +358,7 @@ export class SubagentThreadRegistry {
   spawn(spec: SubagentThreadSpec): SubagentThread {
     this.assertOpen();
     this.validateSpec(spec);
+    this.assertUniqueDisplayName(spec.displayName, spec.parentId);
     const rawId = this.createId();
     requireText(rawId, "thread id");
     const id = rawId as SubagentThreadId;
@@ -280,12 +368,15 @@ export class SubagentThreadRegistry {
     const thread: SubagentThread = {
       id,
       parentId: spec.parentId,
+      displayName: spec.displayName,
       role: spec.role,
       prompt: spec.prompt,
       model: spec.model,
       tools: [...spec.tools],
       capabilityBoundary: copyBoundary(spec.capabilityBoundary),
+      session: copySession(spec.session),
       handoff: copyHandoff(spec.handoff),
+      attempt: 1,
       state: "queued",
       usage: emptyUsage(),
       trace: [],
@@ -337,13 +428,16 @@ export class SubagentThreadRegistry {
       throw new Error(`steering message exceeds ${this.maxSteeringMessageLength} characters`);
     }
     thread.steering.push({ id: ++this.nextSteeringId, at: this.now(), message });
-    if (thread.steering.length > this.maxSteeringMessages) thread.steering.splice(0, thread.steering.length - this.maxSteeringMessages);
+    if (thread.steering.length > this.maxSteeringMessages) thread.steering.splice(this.maxSteeringMessages);
     this.changed(thread, "steer");
     return snapshot(thread);
   }
 
   complete(id: SubagentThreadId, completion: SubagentCompletion = {}): SubagentThread {
     const thread = this.requireState(id, ["active"]);
+    const result = completion.result !== undefined ? completion.result : thread.result;
+    if (result === undefined || result === null) throw new Error(`Cannot complete thread ${id} without a usable result`);
+    requireText(result, "result");
     this.applyPatch(thread, completion);
     thread.state = "done";
     thread.timestamps.endedAt = this.now();
@@ -397,11 +491,107 @@ export class SubagentThreadRegistry {
     return thread ? snapshot(thread) : undefined;
   }
 
+  resolve(reference: string, parentId?: SubagentThreadId): SubagentThread | undefined {
+    if (typeof reference !== "string") return undefined;
+    const exact = this.threads.get(reference as SubagentThreadId);
+    if (exact) return snapshot(exact);
+    const name = reference.toLocaleLowerCase();
+    const match = [...this.threads.values()].find((thread) =>
+      thread.parentId === parentId && thread.displayName.toLocaleLowerCase() === name,
+    );
+    return match ? snapshot(match) : undefined;
+  }
+
+  hydrate(thread: SubagentThread): SubagentThread {
+    this.assertOpen();
+    this.validateThreadSnapshot(thread);
+    if (this.threads.has(thread.id)) throw new Error(`Duplicate thread id ${thread.id}`);
+    this.assertUniqueDisplayName(thread.displayName, thread.parentId);
+
+    const hydrated = snapshot(thread);
+    if (hydrated.state === "queued" || hydrated.state === "active") {
+      hydrated.state = "orphaned";
+      hydrated.stopReason = "parent_restarted";
+    }
+    this.threads.set(hydrated.id, hydrated);
+    for (const message of hydrated.steering) this.nextSteeringId = Math.max(this.nextSteeringId, message.id);
+    return snapshot(hydrated);
+  }
+
+  resume(id: SubagentThreadId, prompt?: string): SubagentThread {
+    const thread = this.requireState(id, ["done", "failed", "stopped", "orphaned"]);
+    if (prompt !== undefined) {
+      requireText(prompt, "prompt");
+      thread.prompt = prompt;
+    }
+    thread.attempt += 1;
+    thread.result = undefined;
+    thread.failure = undefined;
+    thread.stopReason = undefined;
+    delete thread.timestamps.startedAt;
+    delete thread.timestamps.endedAt;
+    thread.state = "queued";
+    this.changed(thread, "resume");
+    return snapshot(thread);
+  }
+
+  waitForTerminal(ids: readonly SubagentThreadId[], timeoutMs: number): Promise<SubagentWaitResult> {
+    const threadIds = [...ids];
+    if (threadIds.length === 0) {
+      return Promise.resolve({
+        threadIds,
+        completedThreadIds: [],
+        pendingThreadIds: [],
+        timedOut: false,
+        waitedMs: 0,
+        threads: [],
+      });
+    }
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > MAX_WAIT_TIMEOUT_MS) {
+      throw new Error(`timeoutMs must be an integer from 0 to ${MAX_WAIT_TIMEOUT_MS}`);
+    }
+    for (const id of threadIds) this.requireThread(id);
+
+    const startedAt = Date.now();
+    const currentThreads = (): SubagentThread[] => threadIds.map((id) => snapshot(this.threads.get(id)!));
+    const makeResult = (timedOut: boolean): SubagentWaitResult => {
+      const threads = currentThreads();
+      const completedThreadIds = threads.filter((thread) => isTerminal(thread.state)).map((thread) => thread.id);
+      return {
+        threadIds,
+        completedThreadIds,
+        pendingThreadIds: threads.filter((thread) => !isTerminal(thread.state)).map((thread) => thread.id),
+        timedOut,
+        waitedMs: Math.max(0, Date.now() - startedAt),
+        threads,
+      };
+    };
+    const allTerminal = (): boolean => threadIds.every((id) => isTerminal(this.threads.get(id)!.state));
+    if (allTerminal()) return Promise.resolve(makeResult(false));
+
+    return new Promise<SubagentWaitResult>((resolve) => {
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let unsubscribe = (): void => {};
+      const finish = (timedOut: boolean): void => {
+        if (settled) return;
+        settled = true;
+        unsubscribe();
+        if (timer !== undefined) clearTimeout(timer);
+        resolve(makeResult(timedOut));
+      };
+      unsubscribe = this.subscribe((change) => {
+        if (threadIds.includes(change.thread.id) && allTerminal()) finish(false);
+      });
+      timer = setTimeout(() => finish(true), timeoutMs);
+    });
+  }
+
   listActive(): SubagentThread[] {
     return this.list((thread) => thread.state === "active");
   }
 
-  /** Returns all terminal records: done, failed, and stopped. */
+  /** Returns all terminal records: done, failed, stopped, and orphaned. */
   listDone(): SubagentThread[] {
     return this.list((thread) => isTerminal(thread.state));
   }
@@ -468,10 +658,15 @@ export class SubagentThreadRegistry {
   }
 
   private validateSpec(spec: SubagentThreadSpec): void {
+    if (!spec || typeof spec !== "object") throw new Error("thread spec must be an object");
+    if (spec.parentId !== undefined) requireText(spec.parentId, "parent id");
+    validateDisplayName(spec.displayName);
     requireText(spec.role, "role");
     requireText(spec.prompt, "prompt");
     requireText(spec.model, "model");
     validateBoundary(spec.capabilityBoundary);
+    validateSession(spec.session);
+    if (!Array.isArray(spec.tools)) throw new Error("tools must be an array");
     const tools = new Set<string>();
     for (const tool of spec.tools) {
       requireText(tool, "tool");
@@ -481,6 +676,31 @@ export class SubagentThreadRegistry {
     if (spec.handoff) validateHandoff(spec.handoff);
   }
 
+  private validateThreadSnapshot(thread: SubagentThread): void {
+    if (!thread || typeof thread !== "object") throw new Error("thread snapshot must be an object");
+    requireText(thread.id, "thread id");
+    this.validateSpec(thread);
+    if (!(["queued", "active", "done", "failed", "stopped", "orphaned", "closed"] as string[]).includes(thread.state)) {
+      throw new Error(`Unknown thread state ${thread.state}`);
+    }
+    requirePositiveInteger(thread.attempt, "attempt");
+    validateCompleteUsage(thread.usage);
+    if (!Array.isArray(thread.trace)) throw new Error("trace must be an array");
+    thread.trace.forEach(validateTraceEvent);
+    if (!Array.isArray(thread.steering)) throw new Error("steering must be an array");
+    thread.steering.forEach(validateSteeringMessage);
+    if (thread.result !== undefined) requireText(thread.result, "result");
+    if (thread.failure !== undefined) {
+      if (!thread.failure || typeof thread.failure !== "object") throw new Error("failure must be an object");
+      requireText(thread.failure.message, "failure.message");
+      if (thread.failure.code !== undefined) requireText(thread.failure.code, "failure.code");
+    }
+    if (thread.stopReason !== undefined) requireText(thread.stopReason, "stopReason");
+    if (typeof thread.evicted !== "boolean") throw new Error("evicted must be a boolean");
+    validateTimestamps(thread.timestamps);
+    requirePositiveInteger(thread.version, "version");
+  }
+
   private applyPatch(thread: SubagentThread, patch: SubagentThreadPatch): void {
     if (patch.usage) {
       validateUsage(patch.usage);
@@ -500,6 +720,15 @@ export class SubagentThreadRegistry {
     return [...this.threads.values()].filter(matches).map(snapshot);
   }
 
+  private assertUniqueDisplayName(displayName: string, parentId?: SubagentThreadId): void {
+    const name = displayName.toLocaleLowerCase();
+    if ([...this.threads.values()].some((thread) =>
+      thread.parentId === parentId && thread.displayName.toLocaleLowerCase() === name,
+    )) {
+      throw new Error(`display name ${displayName} already exists for this parent`);
+    }
+  }
+
   private requireThread(id: SubagentThreadId): SubagentThread {
     this.assertOpen();
     const thread = this.threads.get(id);