@compilr-dev/sdk 0.17.18 → 0.18.0

package/dist/team/consult-tool.d.ts

@@ -40,31 +40,57 @@ export interface ConsultResult {
      *  (target run exceeded max iterations, transport error, etc.). */
     error?: string;
 }
+/** Default wall-clock cap for a whole consult sub-run (ms). */
+export declare const DEFAULT_CONSULT_TIMEOUT_MS = 180000;
+/**
+ * Options passed to `onConsult` alongside the question. Additive — hosts
+ * that predate the timeout work can ignore `signal` and keep compiling,
+ * but they will NOT get the hang protection until they forward it into
+ * their target `agent.run(..., { signal })`.
+ */
+export interface ConsultRunOptions {
+    /**
+     * Aborts when the wall-clock timeout fires (or the host links its own
+     * borrower signal to it). Implementations MUST forward this into the
+     * target agent's run so an expired consult actually stops the sub-run
+     * instead of orphaning it.
+     */
+    signal: AbortSignal;
+}
 /**
  * Configuration for `createConsultTool`.
  *
  * `onConsult` is intentionally platform-shaped — each host runs sub-agents
  * differently (CLI's REPL sub-context, Desktop's agent-manager, in-process
- * Agent.run). The SDK owns validation and message format; the platform
- * owns the actual run.
+ * Agent.run). The SDK owns validation, message format, and the wall-clock
+ * timeout; the platform owns the actual run.
  */
 export interface ConsultToolConfig {
     /** The team instance — used to validate target agent membership. */
     team: AgentTeam;
     /** The borrowing agent's ID. */
     currentAgentId: string;
+    /**
+     * Wall-clock cap for the whole consult sub-run, in ms. The SDK arms a
+     * timer, aborts `signal` on expiry, and returns a recoverable timeout
+     * error to the borrower's LLM. Defaults to {@link DEFAULT_CONSULT_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
     /**
      * Platform-specific consult handler. Called after validation passes.
      * Should:
      *   1. Synthesise the question message (use `buildConsultQuestionMessage`).
-     *   2. Run the target agent against that message (sub-run, not a turn
-     *      in the borrower's conversation).
+     *   2. Run the target agent against that message, **history-aware** (the
+     *      target's real agent/history — NOT a throwaway or snapshot-restored
+     *      run), forwarding `opts.signal` into the run so the timeout can
+     *      abort it.
      *   3. Return the target's final response text.
      *
-     * The target's conversation history is NOT mutated by a consult — the
-     * call is transient.
+     * As of consult v2 the target DOES remember the exchange — the historical
+     * "transient / history not mutated" contract is removed. See
+     * `consult-persistent-conversation-spec.md`.
      */
-    onConsult: (targetAgentId: string, question: string, context: string | undefined) => Promise<{
+    onConsult: (targetAgentId: string, question: string, context: string | undefined, opts: ConsultRunOptions) => Promise<{
         answer: string;
         error?: string;
     }>;

package/dist/team/consult-tool.js

@@ -21,6 +21,8 @@
  *   /workspace/project-docs/00-requirements/compilr-dev-sdk/consult-tool-spec.md
  */
 import { defineTool } from '@compilr-dev/agents';
+/** Default wall-clock cap for a whole consult sub-run (ms). */
+export const DEFAULT_CONSULT_TIMEOUT_MS = 180_000;
 // =============================================================================
 // Canonical question-message format
 // =============================================================================
@@ -63,10 +65,12 @@ export function buildConsultQuestionMessage(input) {
  */
 export function createConsultTool(config) {
     const { team, currentAgentId, onConsult } = config;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_CONSULT_TIMEOUT_MS;
     return defineTool({
         name: 'consult',
-        description: 'Ask another specialist a focused question and continue the conversation yourself. ' +
-            'Use this when you need a quick opinion or expertise input from a teammate without giving up the conversation. ' +
+        description: 'Ask a teammate a focused question and continue your own work. ' +
+            'They answer using their own context and remember the exchange, so a consult is a real interaction in their conversation — not a throwaway. ' +
+            'Use this when you need a quick opinion or expertise from a teammate without giving up the conversation. ' +
             'Unlike handoff, you keep ownership — the target answers and control returns to you. ' +
             'Example: $arch can consult $pm on scope, get an answer, and continue designing.',
         inputSchema: {
@@ -123,8 +127,19 @@ export function createConsultTool(config) {
                     error: `Agent "${targetId}" not found in team. Available specialists: ${available || '(none)'}`,
                 };
             }
+            // Wall-clock cap for the whole sub-run. The SDK owns this so BOTH
+            // hosts inherit the hang fix without duplicating timeout logic. On
+            // expiry we abort the signal (the host forwards it into the target
+            // run) and hand the borrower's LLM a recoverable error rather than
+            // hanging "running" forever — the failure mode observed in testing.
+            const ac = new AbortController();
+            const timer = setTimeout(() => {
+                ac.abort(new Error('consult-timeout'));
+            }, timeoutMs);
             try {
-                const { answer, error } = await onConsult(targetId, question, context);
+                const { answer, error } = await onConsult(targetId, question, context, {
+                    signal: ac.signal,
+                });
                 if (error) {
                     return { success: false, error };
                 }
@@ -132,11 +147,23 @@ export function createConsultTool(config) {
                 return { success: true, result };
             }
             catch (err) {
+                if (ac.signal.aborted) {
+                    const seconds = String(Math.round(timeoutMs / 1000));
+                    return {
+                        success: false,
+                        error: `$${targetId} didn't respond in time (${seconds}s). ` +
+                            'It may have a pending question — the request was surfaced in your chat. ' +
+                            'You can try consulting again, ask the user, or proceed without it.',
+                    };
+                }
                 return {
                     success: false,
                     error: `Consult failed: ${err instanceof Error ? err.message : String(err)}`,
                 };
             }
+            finally {
+                clearTimeout(timer);
+            }
         },
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.17.18",
+  "version": "0.18.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",