@the-open-engine/zeroshot 6.10.2 → 6.12.0

package/src/agent/output-reformatter.js

@@ -4,16 +4,20 @@
  * When an LLM outputs markdown/text instead of JSON despite schema instructions,
  * this module attempts to extract/reformat the content into valid JSON.
  *
- * STATUS: SDK NOT IMPLEMENTED - Reformatting is not available.
- * This module exists for future extension when SDK support is added.
- *
- * To enable reformatting:
- * 1. Implement SDK support in the provider (getSDKEnvVar, callSimple)
- * 2. The reformatOutput() function will then work automatically
+ * Opencode output can be reformatted through its CLI when direct JSON extraction fails.
+ * Other providers remain on their own extraction paths and never depend on the opencode binary.
  */
 
 const DEFAULT_MAX_ATTEMPTS = 3;
 
+
+function createCancellationError() {
+  const error = new Error('Output reformatting cancelled');
+  error.code = 'REFORMAT_CANCELLED';
+  return error;
+}
+
+
 /**
  * Build the reformatting prompt
  *
@@ -27,7 +31,9 @@ function buildReformatPrompt(rawOutput, schema, previousError = null) {
   // Truncate long outputs to avoid context limits
   const truncatedOutput = rawOutput.length > 4000 ? rawOutput.slice(-4000) : rawOutput;
 
-  let prompt = `Convert this text into a JSON object matching the schema.
+  let prompt = `CRITICAL: Do NOT use any tools. Do NOT read, write, or edit any files. Do NOT explore the codebase. This is a pure text-to-JSON transformation — respond with JSON only.
+
+Convert this text into a JSON object matching the schema.
 
 ## SCHEMA
 \`\`\`json
@@ -58,44 +64,45 @@ Fix this issue in your response.`;
 }
 
 /**
- * Attempt to reformat non-JSON output into valid JSON
- *
- * STATUS: SDK NOT IMPLEMENTED - This function always throws.
- * When SDK support is added to providers, this will work automatically.
+ * This fallback is intentionally scoped to opencode agents. It participates in agent
+ * cancellation so retries cannot outlive cluster shutdown.
  *
  * @param {Object} options
  * @param {string} options.rawOutput - The non-JSON output to reformat
  * @param {Object} options.schema - Target JSON schema
- * @param {string} options.providerName - Provider name (claude, codex, gemini, opencode)
+ * @param {string} options.providerName - Active provider name
  * @param {number} [options.maxAttempts=3] - Maximum reformatting attempts
  * @param {Function} [options.onAttempt] - Callback for each attempt (attempt, error)
+ * @param {Function} [options.isCancelled] - Returns true after agent cancellation
+ * @param {Function} options.runReformat - Runs the prompt in the active agent execution context
  * @returns {Promise<Object>} The reformatted JSON object
- * @throws {Error} Always throws - SDK not implemented
+ * @throws {Error} If the provider is unsupported, cancellation occurs, or attempts fail
  */
-function reformatOutput({
+async function reformatOutput({
   rawOutput,
-  schema: _schema,
+  schema,
   providerName,
-  maxAttempts: _maxAttempts = DEFAULT_MAX_ATTEMPTS,
-  onAttempt: _onAttempt,
+  maxAttempts = DEFAULT_MAX_ATTEMPTS,
+  onAttempt,
+  isCancelled = () => false,
+  runReformat,
 }) {
-  // SDK not implemented - reformatting not available
-  // When SDK support is added, uncomment the implementation below
-  return Promise.reject(
-    new Error(
-      `Output reformatting not available: SDK not implemented for provider "${providerName}". ` +
+  if (providerName !== 'opencode') {
+    throw new Error(
+      `Output reformatting not available for provider "${providerName}". ` +
         `Agent output must be valid JSON. Raw output (last 200 chars): ${(rawOutput || '').slice(-200)}`
-    )
-  );
+    );
+  }
+  if (typeof runReformat !== 'function') {
+    throw new Error('Output reformatting requires the active agent execution context');
+  }
 
-  // FUTURE: When SDK support is added to providers, uncomment this:
-  /*
-  const { getProvider } = require('../providers');
-  const provider = getProvider(providerName);
 
+  const { extractJsonFromOutput } = require('./output-extraction');
   let lastError = null;
 
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (isCancelled()) throw createCancellationError();
     if (onAttempt) {
       onAttempt(attempt, lastError);
     }
@@ -103,23 +110,19 @@ function reformatOutput({
     const prompt = buildReformatPrompt(rawOutput, schema, lastError);
 
     try {
-      const result = await provider.callSimple(prompt, {
-        level: 'level1',
-        maxTokens: 2000,
-      });
-
+      const result = await runReformat(prompt);
+      if (isCancelled()) throw createCancellationError();
       if (!result?.success) {
-        lastError = result?.error || 'API call failed';
+        lastError = result?.error || 'reformat task failed';
         continue;
       }
-
-      if (!result?.text) {
-        lastError = 'Empty response from reformatting model';
+      const output = result.output;
+      if (!output) {
+        lastError = 'reformat task returned no output';
         continue;
       }
 
-      const parsed = extractJsonFromOutput(result.text, providerName);
-
+      const parsed = extractJsonFromOutput(output, 'opencode');
       if (!parsed) {
         lastError = 'Could not extract JSON from reformatted output';
         continue;
@@ -133,14 +136,24 @@ function reformatOutput({
 
       return parsed;
     } catch (err) {
+      if (
+        err.code === 'REFORMAT_CANCELLED' ||
+        err.code === 'AGENT_TASK_TIMEOUT' ||
+        err.nestedExecutionLifecycle === true ||
+        err.retainTaskHandle === true ||
+        err.permanent === true ||
+        err.terminationExhausted === true
+      ) {
+        throw err;
+      }
       lastError = err.message;
     }
   }
 
   throw new Error(
-    `Failed to reformat output after ${maxAttempts} attempts. Last error: ${lastError}`
+    `Failed to reformat output after ${maxAttempts} attempts (provider "${providerName}"). ` +
+      `Last error: ${lastError}. Raw output (last 200 chars): ${(rawOutput || '').slice(-200)}`
   );
-  */
 }
 
 /**

package/src/agent/pr-verification.js

@@ -335,9 +335,12 @@ function resolveFieldValue(structuredOutput, fieldNames) {
   return null;
 }
 
-function resolvePrClaimsFromOutput({ output, providerName, adapter }) {
+function resolvePrClaimsFromOutput({ output, parsedResult, providerName, adapter }) {
   const { extractJsonFromOutput } = require('./output-extraction');
-  const structuredOutput = extractJsonFromOutput(output, providerName) || {};
+  const structuredOutput =
+    parsedResult && typeof parsedResult === 'object'
+      ? parsedResult
+      : extractJsonFromOutput(output, providerName) || {};
 
   const structuredUrl = resolveFieldValue(structuredOutput, getClaimUrlFieldCandidates(adapter));
   const structuredNumber = resolveFieldValue(
@@ -586,7 +589,12 @@ async function verifyPullRequest({ result, agent, autoMerge }) {
   const adapter = getVerificationAdapter(platform);
   const providerName =
     typeof agent?._resolveProvider === 'function' ? agent._resolveProvider() : 'claude';
-  const claims = resolvePrClaimsFromOutput({ output: result.output, providerName, adapter });
+  const claims = resolvePrClaimsFromOutput({
+    output: result.output,
+    parsedResult: result.parsedResult,
+    providerName,
+    adapter,
+  });
 
   if (handleBlockedPusherOutcome({ claims, platform, agent })) {
     return;

package/src/agent/task-execution-handle.js

@@ -0,0 +1,373 @@
+function isTerminationConfirmed(termination) {
+  return termination?.forced !== false || termination?.alreadyTerminal === true;
+}
+const MAX_DEADLINE_CLEANUP_ATTEMPTS = 3;
+
+/**
+ * TaskExecutionHandle — first-class reentrant task-execution handle.
+ *
+ * Created BEFORE the provider process is spawned so cancellation is possible
+ * even before a task ID or PID is known. Owns the process tree, tracks late
+ * task-ID / PID assignment, and supports nested (child) executions that never
+ * overwrite the parent's identity.
+ */
+class TaskExecutionHandle {
+  constructor(agentId) {
+    /** @type {string} Owning agent id (immutable). */
+    this.agentId = agentId;
+    /** @type {string|null} Zeroshot task id, assigned once after registration. */
+    this._taskId = null;
+    /** @type {number|null} Real CLI process pid, assigned once after registration. */
+    this._pid = null;
+    /** @type {import('child_process').ChildProcess|null} Launch wrapper process. */
+    this._proc = null;
+    this._cancelled = false;
+    this._cancelReason = null;
+    this._cancelDetails = {};
+    this._cancelAction = null;
+    this._failClosedAction = null;
+    this._failClosedError = null;
+    this._invokedCancelActions = new Set();
+    this._cancelActionPromises = [];
+    this._lastCancellationResult = undefined;
+    this._executionFinished = false;
+    this._retainOwnership = false;
+    this.settled = false;
+    this._resolveSettle = null;
+    this._settlePromise = new Promise((resolve) => {
+      this._resolveSettle = resolve;
+    });
+    /** @type {ReturnType<typeof setTimeout>|null} */
+    this._killTimer = null;
+    /** @type {ReturnType<typeof setTimeout>|null} */
+    this._deadlineTimer = null;
+  }
+
+  get taskId() {
+    return this._taskId;
+  }
+
+  get pid() {
+    return this._pid;
+  }
+
+  get isCancelled() {
+    return this._cancelled;
+  }
+
+  get cancelReason() {
+    return this._cancelReason;
+  }
+
+  get cancelDetails() {
+    return this._cancelDetails;
+  }
+
+  attachProcess(proc) {
+    this._proc = proc;
+    const clearWrapperKill = () => this._clearKillTimer();
+    proc.once('close', clearWrapperKill);
+    proc.once('error', clearWrapperKill);
+    if (this._cancelled) {
+      this._killProcess();
+    }
+  }
+
+  assignTaskId(taskId) {
+    if (this._taskId && this._taskId !== taskId) {
+      throw new Error(`Nested execution task ID changed from ${this._taskId} to ${taskId}`);
+    }
+    this._taskId = taskId;
+    if (this._cancelled) {
+      this._killProcess();
+      this._invokeCancelAction();
+    }
+  }
+
+  assignPid(pid) {
+    if (this._pid && this._pid !== pid) {
+      throw new Error(`Nested execution PID changed from ${this._pid} to ${pid}`);
+    }
+    this._pid = pid;
+  }
+
+  setCancelAction(action) {
+    const previousAction = this._cancelAction;
+    this._cancelAction = action;
+    if (this._cancelled) {
+      this._invokeCancelAction();
+    }
+    return previousAction;
+  }
+
+  setFailClosedAction(action) {
+    this._failClosedAction = action;
+    if (this._failClosedError) {
+      action(this._failClosedError);
+    }
+  }
+
+  failClosed(error) {
+    if (this.settled || this._failClosedError) return false;
+    this._retainOwnership = true;
+    this._failClosedError = error;
+    if (!error.taskId && this._taskId) {
+      error.taskId = this._taskId;
+    }
+    if (this._failClosedAction) {
+      this._failClosedAction(error);
+    }
+    return true;
+  }
+
+  cancel(reason = 'Task cancelled', details = {}) {
+    if (!this._cancelled) {
+      this._cancelled = true;
+      this._cancelReason = reason;
+      this._cancelDetails = details;
+    }
+    this._clearDeadlineTimer();
+    this._killProcess();
+    this._invokeCancelAction();
+    return this.waitForCancellation();
+  }
+
+  async waitForCancellation() {
+    let observedCount = -1;
+    let results = [];
+    try {
+      while (observedCount !== this._cancelActionPromises.length) {
+        observedCount = this._cancelActionPromises.length;
+        results = await Promise.all(this._cancelActionPromises);
+      }
+    } catch (error) {
+      this._retainOwnership = true;
+      this._invokedCancelActions.delete(this._cancelAction);
+      this._cancelActionPromises = [];
+      throw error;
+    }
+    const observedTermination = results.at(-1);
+    if (observedTermination !== undefined && observedTermination !== null) {
+      this._lastCancellationResult = observedTermination;
+    }
+    const termination =
+      observedTermination !== undefined && observedTermination !== null
+        ? observedTermination
+        : this._lastCancellationResult;
+    if (termination === undefined || termination === null) {
+      return termination;
+    }
+    if (!isTerminationConfirmed(termination)) {
+      this._retainOwnership = true;
+      this._invokedCancelActions.delete(this._cancelAction);
+      this._cancelActionPromises = [];
+    } else {
+      this._retainOwnership = false;
+      if (this._executionFinished) {
+        this.markSettled();
+      }
+    }
+    return termination;
+  }
+
+  armDeadline(timeoutMs) {
+    if (timeoutMs <= 0 || this.settled) return;
+    this._clearDeadlineTimer();
+    this._deadlineTimer = setTimeout(() => {
+      this._deadlineTimer = null;
+      this._cancelAtDeadline(timeoutMs).catch(() => {
+        // failClosed records the permanent error before notifying the execution owner.
+      });
+    }, timeoutMs);
+  }
+
+  async _cancelAtDeadline(timeoutMs) {
+    const reason = `Nested task timed out after ${timeoutMs}ms`;
+    let lastError = null;
+    let termination = null;
+    let attempts = 0;
+    for (attempts = 1; attempts <= MAX_DEADLINE_CLEANUP_ATTEMPTS; attempts++) {
+      try {
+        termination = await this.cancel(reason, { code: 'AGENT_TASK_TIMEOUT' });
+        if (termination && isTerminationConfirmed(termination)) return;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    const detail =
+      lastError?.message || termination?.reason || 'task termination was not confirmed';
+    const error = new Error(
+      `Failed to terminate nested task ${this._taskId || 'before task ID assignment'} ` +
+        `after ${attempts - 1} deadline cleanup attempts: ${detail}`
+    );
+    error.code = 'NESTED_TASK_TERMINATION_EXHAUSTED';
+    error.taskId = this._taskId;
+    error.permanent = true;
+    error.restartExhausted = true;
+    error.terminationExhausted = true;
+    error.terminationAttempts = attempts - 1;
+    error.retainTaskHandle = true;
+    error.nestedExecutionLifecycle = true;
+    this.failClosed(error);
+  }
+
+  retainOwnership() {
+    this._retainOwnership = true;
+  }
+
+  finishExecution() {
+    this._executionFinished = true;
+    if (!this._retainOwnership) {
+      this.markSettled();
+    }
+  }
+
+  markSettled() {
+    if (this.settled) return;
+    this.settled = true;
+    this._clearKillTimer();
+    this._clearDeadlineTimer();
+    this._resolveSettle();
+  }
+
+  async settle() {
+    await this._settlePromise;
+  }
+
+  _invokeCancelAction() {
+    const action = this._cancelAction;
+    if (!action || this._invokedCancelActions.has(action)) return;
+    this._invokedCancelActions.add(action);
+    const cancellation = Promise.resolve().then(() =>
+      action(this._cancelReason, this._cancelDetails)
+    );
+    this._cancelActionPromises.push(cancellation);
+  }
+
+  _clearDeadlineTimer() {
+    if (this._deadlineTimer) {
+      clearTimeout(this._deadlineTimer);
+      this._deadlineTimer = null;
+    }
+  }
+
+  _clearKillTimer() {
+    if (this._killTimer) {
+      clearTimeout(this._killTimer);
+      this._killTimer = null;
+    }
+  }
+
+  _killProcess() {
+    if (!this._proc || this.settled) return;
+    try {
+      this._proc.kill('SIGTERM');
+      const proc = this._proc;
+      this._clearKillTimer();
+      this._killTimer = setTimeout(() => {
+        this._killTimer = null;
+        if (!this.settled) {
+          try {
+            proc.kill('SIGKILL');
+          } catch {
+            // Process already exited.
+          }
+        }
+      }, 3000);
+    } catch {
+      // Process already exited.
+    }
+  }
+}
+
+class NestedExecutionRegistry {
+  constructor(agentId) {
+    this.agentId = agentId;
+    this._handles = new Set();
+    this._cancellation = null;
+  }
+
+  get size() {
+    return this._handles.size;
+  }
+
+  get hasActive() {
+    return this._handles.size > 0;
+  }
+
+  get activeTaskIds() {
+    return [...this._handles].map((handle) => handle.taskId).filter(Boolean);
+  }
+
+  register(handle) {
+    if (this._cancellation) {
+      const error = new Error(this._cancellation.reason);
+      error.code = this._cancellation.details.code || 'REFORMAT_CANCELLED';
+      error.nestedExecutionCancellation = true;
+      error.nestedExecutionLifecycle = true;
+      throw error;
+    }
+    if (!(handle instanceof TaskExecutionHandle)) {
+      throw new TypeError('Nested execution registry accepts TaskExecutionHandle instances only');
+    }
+    if (handle.agentId !== this.agentId) {
+      throw new Error(
+        `Nested execution owner mismatch: registry ${this.agentId}, handle ${handle.agentId}`
+      );
+    }
+    this._handles.add(handle);
+    return handle;
+  }
+
+  unregister(handle) {
+    if (!handle.settled) {
+      throw new Error('Cannot unregister a nested execution before settlement');
+    }
+    this._handles.delete(handle);
+  }
+
+  failClosed(error) {
+    let dispatched = false;
+    for (const handle of this._handles) {
+      dispatched = handle.failClosed(error) || dispatched;
+    }
+    return dispatched;
+  }
+
+  async cancelAll(reason = 'Task cancelled', details = {}) {
+    this._cancellation = { reason, details };
+    try {
+      const handles = [...this._handles];
+      const terminations = await Promise.all(
+        handles.map(async (handle) => {
+          const termination = await handle.cancel(reason, details);
+          if (isTerminationConfirmed(termination)) {
+            await handle.settle();
+            this.unregister(handle);
+          }
+          return termination;
+        })
+      );
+      const failed = terminations.find(
+        (termination) => !isTerminationConfirmed(termination)
+      );
+      return failed || { forced: true, nested: terminations };
+    } finally {
+      this._cancellation = null;
+    }
+  }
+}
+
+function getNestedExecutionRegistry(agent) {
+  if (!agent.nestedExecutions) {
+    agent.nestedExecutions = new NestedExecutionRegistry(agent.id);
+  }
+  return agent.nestedExecutions;
+}
+
+module.exports = {
+  getNestedExecutionRegistry,
+  NestedExecutionRegistry,
+  TaskExecutionHandle,
+};

package/src/agent-cli-provider/adapters/opencode.ts

@@ -55,6 +55,9 @@ function addOpencodeOptionalArgs(args: string[], options: BuildProviderCommandOp
   ) {
     args.push('--format', 'json');
   }
+  if (options.agentName) {
+    args.push('--agent', options.agentName);
+  }
 
   if (options.modelSpec?.model) {
     args.push('--model', options.modelSpec.model);

package/src/agent-cli-provider/types.ts

@@ -268,6 +268,7 @@ export interface BuildProviderCommandOptions {
   readonly outputFormat?: OutputFormat;
   readonly jsonSchema?: unknown;
   readonly cwd?: string;
+  readonly agentName?: string;
   readonly autoApprove?: boolean;
   readonly resumeSessionId?: string;
   readonly continueSession?: boolean;

package/src/agent-wrapper.js

@@ -25,6 +25,7 @@ const {
 const { findMatchingTrigger, evaluateTrigger } = require('./agent/agent-trigger-evaluator');
 const { executeHook } = require('./agent/agent-hook-executor');
 const { injectInput: injectAgentInput } = require('./agent/agent-input-injector');
+const { NestedExecutionRegistry } = require('./agent/task-execution-handle');
 const {
   spawnClaudeTask,
   followClaudeTaskLogs,
@@ -78,6 +79,8 @@ class AgentWrapper {
     this.currentPromptIdentity = null;
     /** @type {number | null} */
     this.processPid = null; // Track process PID for resource monitoring
+    /** Active child executions never overwrite the parent task identity fields. */
+    this.nestedExecutions = new NestedExecutionRegistry(this.id);
     this.running = false;
     /** @type {Function | null} */
     this.unsubscribe = null;
@@ -512,8 +515,8 @@ class AgentWrapper {
    * Spawn claude-zeroshots process and stream output via message bus
    * @private
    */
-  _spawnClaudeTask(context) {
-    return spawnClaudeTask(this, context);
+  _spawnClaudeTask(context, options = {}) {
+    return spawnClaudeTask(this, context, options);
   }
 
   /**