@compilr-dev/sdk 0.17.18 → 0.18.1

package/dist/platform/tools/canvas-tools.js

@@ -70,7 +70,9 @@ export function createCanvasTools(config) {
             'Bind params in your HTML via CSS custom properties var(--param), [data-bind="param"] text, and ' +
             '[data-show="param"] visibility; for computed updates define window.applyParams(values) in a <script>. ' +
             'Omit canvas_id to create. To EDIT an existing canvas, prefer canvas_edit (str_replace) — it avoids ' +
-            're-sending the whole document; only use canvas_write with canvas_id for a full intentional replace.',
+            're-sending the whole document; only use canvas_write with canvas_id for a full intentional replace. ' +
+            'Before creating a NEW canvas, gather the essentials from the user (purpose, type, key content, style) ' +
+            'with ask_user unless they already specified them — authoring on guessed requirements wastes a full pass.',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/skills/canvas-skills.js

@@ -35,7 +35,13 @@ export const canvasSkill = defineSkill({
 
 ## STEPS
 
-1. **Clarify only if needed.** If the request is concrete, go straight to authoring. If the subject or type is ambiguous, ask ONE short question (what should it show, or which type) — do not run a long interview.
+1. **Collect the essentials from the user FIRST — this is the standard approach.** A canvas is an expensive authoring pass; building it on guessed requirements wastes that pass and lands wide of what the user wanted. So before you author, use **\`ask_user\`** (batch several questions into ONE call) to gather what the canvas needs:
+   - **Purpose & audience** — what is it for, who reads it?
+   - **Canvas type** — infographic, carousel, or board? (Offer the choice unless obvious.)
+   - **Key content / data** — the actual points, numbers, sections, or slides to include. Don't invent data.
+   - **Style / brand** — theme-matched (default) or a specific palette/brand?
+   For open design directions (which layout, which visual approach), present concrete options with **\`propose_alternatives\`** instead of guessing.
+   **Skip questions the user already answered**, and if they gave full detail or explicitly said "just make it / surprise me / your call", go straight to authoring. Keep it to ONE focused round — a short question batch, never a long interview — then build.
 
 2. **Build the canvas in small steps — never one giant tool call.** A canvas is HTML/SVG you emit as tool arguments; a single very large \`canvas_write\` can overrun the output limit, get cut off mid-arguments, and fail. So author it incrementally, and emit each tool call immediately with NO prose preamble (narration competes with the HTML for the same output budget):
    - **2a. First \`canvas_write\`** (type, title, html) = a COMPACT skeleton: the \`<style>\` block, the overall layout, and just the first section or heading. This is the ONLY way to create a canvas — describing it in chat does nothing.

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.1",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",