@twelvehart/orcats 0.2.3 → 0.3.0

package/src/backends/subprocess-termination.ts

@@ -0,0 +1,56 @@
+import type { SubprocessProcess } from "./subprocess-run.ts";
+
+const DefaultSubprocessTerminationGraceMs = 1_000;
+const DefaultSubprocessForceGraceMs = 1_000;
+
+const exitWaitCancellations = new WeakMap<
+  SubprocessProcess,
+  (error: unknown) => void
+>();
+
+export function registerSubprocessExitWaitCancellation(
+  process: SubprocessProcess,
+  cancel: (error: unknown) => void
+): void {
+  exitWaitCancellations.set(process, cancel);
+}
+
+export async function terminateSubprocess(
+  process: SubprocessProcess,
+  gracefulMs = DefaultSubprocessTerminationGraceMs,
+  forceMs = DefaultSubprocessForceGraceMs
+): Promise<void> {
+  try {
+    process.kill("SIGTERM");
+    if (await exitsWithin(process.exit, gracefulMs)) {
+      return;
+    }
+
+    process.kill("SIGKILL");
+    if (!(await exitsWithin(process.exit, forceMs))) {
+      throw new Error("subprocess did not exit after SIGKILL");
+    }
+  } catch (error) {
+    const cancelExitWait = exitWaitCancellations.get(process);
+    exitWaitCancellations.delete(process);
+    cancelExitWait?.(error);
+    throw error;
+  }
+}
+
+async function exitsWithin(
+  exit: Promise<number | null>,
+  timeoutMs: number
+): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<false>((resolve) => {
+    timer = setTimeout(() => {
+      resolve(false);
+    }, Math.max(timeoutMs, 0));
+  });
+  try {
+    return await Promise.race([exit.then(() => true as const), timedOut]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/cli/main.ts

@@ -321,7 +321,8 @@ function describeError(error: unknown): string {
     return error.reason;
   }
   try {
-    return JSON.stringify(error);
+    const serialized = JSON.stringify(error) as string | undefined;
+    return serialized ?? String(error);
   } catch {
     return String(error);
   }

package/src/cli/version.ts

@@ -1 +1 @@
-export const ORCA_VERSION = "0.2.3";
+export const ORCA_VERSION = "0.3.0";

package/src/conversation/conversation.ts

@@ -4,9 +4,15 @@ import {
   type BackendTag,
   type ConversationEvent,
   type RuntimeError,
+  backendFailed,
   unsupportedFeature
 } from "../model/index.ts";
 import { BoundedAsyncQueue } from "./queue.ts";
+import {
+  deferConversationSettlement,
+  markConversationCancellationComplete,
+  registerConversationCancellationFailureHandler
+} from "./settlement-reservation.ts";
 
 export type Outcome<B extends BackendTag = BackendTag> =
   | { readonly type: "success"; readonly result: BackendResult<B> }
@@ -39,6 +45,7 @@ export class StreamConversation<B extends BackendTag> implements Conversation<B>
   private readonly outcome: Promise<Outcome<B>>;
   private settle!: (outcome: Outcome<B>) => void;
   private settled = false;
+  private cancellation: Promise<void> | undefined;
 
   constructor(private readonly options: StreamConversationOptions<B>) {
     this.queue = new BoundedAsyncQueue(options.capacity ?? 32);
@@ -80,21 +87,80 @@ export class StreamConversation<B extends BackendTag> implements Conversation<B>
   }
 
   succeed(result: BackendResult<B>): void {
-    this.complete({ type: "success", result });
+    if (this.cancellation !== undefined) {
+      return;
+    }
+    const outcome: Outcome<B> = { type: "success", result };
+    if (
+      deferConversationSettlement(this, "success", () => {
+        if (this.cancellation === undefined) {
+          this.complete(outcome);
+        }
+      })
+    ) {
+      return;
+    }
+    this.complete(outcome);
   }
 
   fail(error: RuntimeError): void {
-    this.complete({ type: "failed", error });
+    if (this.cancellation !== undefined) {
+      return;
+    }
+    const outcome: Outcome<B> = { type: "failed", error };
+    if (
+      deferConversationSettlement(this, "failure", () => {
+        if (this.cancellation === undefined) {
+          this.complete(outcome);
+        }
+      })
+    ) {
+      return;
+    }
+    this.complete(outcome);
   }
 
-  async cancel(reason?: string): Promise<void> {
+  cancel(reason?: string): Promise<void> {
     if (this.settled) {
-      return;
+      return Promise.resolve();
+    }
+    if (this.cancellation !== undefined) {
+      return this.cancellation;
     }
 
-    this.abortController.abort(reason);
-    await this.options.onCancel?.(reason);
-    this.complete(reason === undefined ? { type: "cancelled" } : { type: "cancelled", reason });
+    const cancellation = Promise.withResolvers<undefined>();
+    this.cancellation = cancellation.promise;
+    registerConversationCancellationFailureHandler(this, (error: unknown) => {
+      this.completeCancellationFailure(error, cancellation.reject);
+    });
+
+    let cleanup: Promise<void>;
+    try {
+      this.abortController.abort(reason);
+      cleanup = Promise.resolve(this.options.onCancel?.(reason));
+    } catch (error) {
+      this.completeCancellationFailure(error, cancellation.reject);
+      return cancellation.promise;
+    }
+
+    void cleanup.then(
+      () => {
+        const outcome: Outcome<B> =
+          reason === undefined ? { type: "cancelled" } : { type: "cancelled", reason };
+        const publish = (): void => {
+          this.complete(outcome);
+          cancellation.resolve(undefined);
+        };
+        if (!deferConversationSettlement(this, "cancellation", publish)) {
+          publish();
+        }
+        markConversationCancellationComplete(this);
+      },
+      (error: unknown) => {
+        this.completeCancellationFailure(error, cancellation.reject);
+      }
+    );
+    return cancellation.promise;
   }
 
   private complete(outcome: Outcome<B>): void {
@@ -106,4 +172,23 @@ export class StreamConversation<B extends BackendTag> implements Conversation<B>
     this.queue.close();
     this.settle(outcome);
   }
+
+  private completeCancellationFailure(
+    error: unknown,
+    rejectCancellation: (reason?: unknown) => void
+  ): void {
+    const message = error instanceof Error ? error.message : String(error);
+    const outcome: Outcome<B> = {
+      type: "failed",
+      error: backendFailed(this.backend, `${this.backend} cancellation cleanup failed: ${message}`)
+    };
+    const publish = (): void => {
+      this.complete(outcome);
+      rejectCancellation(error);
+    };
+    if (!deferConversationSettlement(this, "cancellation_failure", publish)) {
+      publish();
+    }
+    markConversationCancellationComplete(this);
+  }
 }

package/src/conversation/settlement-reservation.ts

@@ -0,0 +1,127 @@
+type SettlementKind = "success" | "cancellation" | "failure" | "cancellation_failure";
+
+const settlementPriority: Readonly<Record<SettlementKind, number>> = {
+  success: 0,
+  failure: 1,
+  cancellation: 2,
+  cancellation_failure: 3
+};
+
+interface PendingSettlement {
+  readonly kind: SettlementKind;
+  readonly publish: () => void;
+}
+
+interface SettlementReservation {
+  depth: number;
+  pending?: PendingSettlement;
+}
+
+const reservations = new WeakMap<object, SettlementReservation>();
+
+interface CancellationCompletion {
+  readonly promise: Promise<void>;
+  readonly resolve: () => void;
+  completed: boolean;
+}
+
+const cancellationCompletions = new WeakMap<object, CancellationCompletion>();
+const cancellationFailureHandlers = new WeakMap<object, (error: unknown) => void>();
+
+function cancellationCompletion(conversation: object): CancellationCompletion {
+  const existing = cancellationCompletions.get(conversation);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const deferred = Promise.withResolvers<undefined>();
+  const created: CancellationCompletion = {
+    promise: deferred.promise,
+    resolve: () => {
+      deferred.resolve(undefined);
+    },
+    completed: false
+  };
+  cancellationCompletions.set(conversation, created);
+  return created;
+}
+
+export function observeConversationCancellationCompletion(
+  conversation: object
+): Promise<void> {
+  return cancellationCompletion(conversation).promise;
+}
+
+export function markConversationCancellationComplete(conversation: object): void {
+  const completion = cancellationCompletion(conversation);
+  if (completion.completed) {
+    return;
+  }
+  completion.completed = true;
+  completion.resolve();
+}
+
+export function registerConversationCancellationFailureHandler(
+  conversation: object,
+  handler: (error: unknown) => void
+): void {
+  cancellationFailureHandlers.set(conversation, handler);
+}
+
+export function reportConversationCancellationFailure(
+  conversation: object,
+  error: unknown
+): boolean {
+  const handler = cancellationFailureHandlers.get(conversation);
+  if (handler === undefined) {
+    return false;
+  }
+  handler(error);
+  return true;
+}
+
+export function reserveConversationSettlement(conversation: object): () => void {
+  const reservation = reservations.get(conversation) ?? { depth: 0 };
+  reservation.depth += 1;
+  reservations.set(conversation, reservation);
+  let released = false;
+
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    reservation.depth -= 1;
+    if (reservation.depth > 0) {
+      return;
+    }
+
+    reservations.delete(conversation);
+    const pending = reservation.pending;
+    delete reservation.pending;
+    pending?.publish();
+  };
+}
+
+export function isConversationSettlementReserved(conversation: object): boolean {
+  return reservations.has(conversation);
+}
+
+export function deferConversationSettlement(
+  conversation: object,
+  kind: SettlementKind,
+  publish: () => void
+): boolean {
+  const reservation = reservations.get(conversation);
+  if (reservation === undefined) {
+    return false;
+  }
+
+  if (
+    reservation.pending === undefined ||
+    settlementPriority[kind] > settlementPriority[reservation.pending.kind]
+  ) {
+    reservation.pending = { kind, publish };
+  }
+  return true;
+}

package/src/model/backend-config.ts

@@ -4,6 +4,13 @@ import type { SessionId } from "./brand.ts";
 
 export type BackendApprovalPolicy = "never" | "on-request" | "on-failure" | "granular" | "untrusted";
 export type BackendSandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export type CodexReasoningEffort =
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max"
+  | "ultra";
 
 export interface BackendRetryConfig {
   readonly attempts: number;
@@ -17,6 +24,7 @@ export interface StructuredOutputConfig<Output = unknown> {
 
 export interface BackendConfig<B extends BackendTag = BackendTag, Output = unknown> {
   readonly model?: string;
+  readonly reasoningEffort?: B extends "codex" ? CodexReasoningEffort : never;
   readonly systemPrompt?: string;
   readonly approvalPolicy?: BackendApprovalPolicy;
   readonly readOnly?: boolean;