@grackle-ai/server 0.55.0 → 0.56.1

package/dist/system-prompt-builder.js

@@ -1,12 +1,33 @@
 /**
  * Builds system prompts for agent sessions, assembling sections
  * dynamically based on the session type (task vs ad-hoc).
+ *
+ * Orchestrator tasks (canDecompose + depth <= 1) receive rich project
+ * context (task tree, persona roster, environments, findings).
+ * Leaf tasks receive the existing completion-contract template.
+ * Task title and description are NOT included in the system prompt — they
+ * belong in the user prompt (see {@link buildTaskPrompt}).
  */
+/** Build the user-facing prompt from task title, description, and optional notes. */
+export function buildTaskPrompt(title, description, notes) {
+    const parts = [title];
+    if (description) {
+        parts.push(description);
+    }
+    if (notes) {
+        parts.push(`## Notes\n${notes}`);
+    }
+    return parts.join("\n\n");
+}
+// ─── Builder ─────────────────────────────────────────────────
 /**
  * Assembles a system prompt from discrete sections based on session type.
  *
- * Task sessions get task context, completion contract, signal docs, and findings guidance.
+ * Orchestrator tasks get project state, task tree, persona roster, and
+ * decomposition guidelines. Leaf tasks get the existing completion contract.
  * Ad-hoc sessions get only the MCP note and persona prompt.
+ * Task title and description are NOT included here — they belong in the user prompt
+ * (see {@link buildTaskPrompt}).
  */
 export class SystemPromptBuilder {
     options;
@@ -21,16 +42,214 @@ export class SystemPromptBuilder {
             sections.push(this.options.personaPrompt);
         }
         if (this.options.task) {
-            sections.push(this.buildTaskContext());
-            sections.push(this.buildCompletionContract());
-            sections.push(this.buildSubtaskSection());
-            sections.push(this.buildSignalSection());
-            sections.push(this.buildFindingsSection());
+            if (this.isOrchestrator()) {
+                sections.push(this.buildOrchestratorTaskContext());
+                sections.push(this.buildWorkspaceContext());
+                sections.push(this.buildTaskTree());
+                sections.push(this.buildAvailablePersonas());
+                sections.push(this.buildAvailableEnvironments());
+                sections.push(this.buildOrchestratorFindingsSection());
+                sections.push(this.buildTriggerContext());
+                sections.push(this.buildDecompositionGuidelines());
+                sections.push(this.buildOrchestratorTools());
+                sections.push(this.buildOrchestratorCompletionContract());
+                sections.push(this.buildSignalSection());
+            }
+            else {
+                // Leaf task: title/description go in the user prompt (buildTaskPrompt), not here.
+                sections.push(this.buildCompletionContract());
+                sections.push(this.buildSubtaskSection());
+                sections.push(this.buildSignalSection());
+                sections.push(this.buildFindingsSection());
+            }
         }
         // MCP note (always included)
         sections.push(this.buildMcpNote());
         return sections.filter(Boolean).join("\n\n");
     }
+    // ─── Orchestrator Detection ──────────────────────────────
+    /**
+     * Determine whether this is an orchestrator task.
+     * Requires canDecompose, shallow depth, AND orchestrator data fields to be
+     * present. This ensures existing callers that pass canDecompose without
+     * the new fields still get the leaf template.
+     */
+    isOrchestrator() {
+        return this.options.canDecompose === true
+            && this.options.taskDepth !== undefined
+            && this.options.taskDepth <= 1
+            && this.options.taskTree !== undefined;
+    }
+    // ─── Orchestrator Sections ───────────────────────────────
+    /** Orchestrator task context with role framing. */
+    buildOrchestratorTaskContext() {
+        const { title, description, notes } = this.options.task;
+        const parts = [
+            `## Your Task: ${title}`,
+            `You are an **orchestrator agent** responsible for decomposing and coordinating work. You do not write code directly — you break work into subtasks, assign personas, manage dependencies, and monitor progress.`,
+        ];
+        if (description) {
+            parts.push(description);
+        }
+        if (notes) {
+            parts.push(`### Notes (from previous attempt or user feedback)\n${notes}`);
+        }
+        return parts.join("\n\n");
+    }
+    /** Workspace metadata section. */
+    buildWorkspaceContext() {
+        const ws = this.options.workspace;
+        if (!ws) {
+            return "";
+        }
+        const lines = [`## Workspace Context`];
+        lines.push(`- **Name**: ${ws.name}`);
+        if (ws.description) {
+            lines.push(`- **Description**: ${ws.description}`);
+        }
+        if (ws.repoUrl) {
+            lines.push(`- **Repository**: ${ws.repoUrl}`);
+        }
+        return lines.join("\n");
+    }
+    /** Hierarchical task tree with statuses, personas, and dependencies. */
+    buildTaskTree() {
+        const nodes = this.options.taskTree;
+        if (!nodes || nodes.length === 0) {
+            return "";
+        }
+        // Build parent → children map
+        const childMap = new Map();
+        for (const node of nodes) {
+            const key = node.parentTaskId || "";
+            const children = childMap.get(key);
+            if (children) {
+                children.push(node);
+            }
+            else {
+                childMap.set(key, [node]);
+            }
+        }
+        // Status summary
+        const counts = new Map();
+        for (const node of nodes) {
+            counts.set(node.status, (counts.get(node.status) || 0) + 1);
+        }
+        const summary = [...counts.entries()]
+            .map(([status, count]) => `${count} ${status}`)
+            .join(", ");
+        // Recursive render
+        const lines = [];
+        const renderNode = (node, indent) => {
+            const pad = "  ".repeat(indent);
+            const persona = node.personaName ? ` (persona: ${node.personaName})` : "";
+            const deps = node.dependsOn.length > 0
+                ? ` [depends on: ${node.dependsOn.join(", ")}]`
+                : "";
+            const branch = node.branch ? ` [branch: ${node.branch}]` : "";
+            const marker = node.id === this.options.taskId ? " <-- YOU" : "";
+            lines.push(`${pad}- [${node.status}] ${node.title}${persona}${deps}${branch}${marker}`);
+            const children = childMap.get(node.id);
+            if (children) {
+                for (const child of children) {
+                    renderNode(child, indent + 1);
+                }
+            }
+        };
+        // Start from root nodes
+        const roots = childMap.get("") || [];
+        for (const root of roots) {
+            renderNode(root, 0);
+        }
+        return `## Task Tree\n\nStatus: ${summary}\n\n${lines.join("\n")}`;
+    }
+    /** Available personas table. */
+    buildAvailablePersonas() {
+        const personas = this.options.availablePersonas;
+        if (!personas || personas.length === 0) {
+            return "";
+        }
+        const rows = personas.map((p) => `| ${p.name} | ${p.description || "—"} | ${p.runtime || "—"} | ${p.model || "—"} |`);
+        return [
+            `## Available Personas`,
+            ``,
+            `| Name | Description | Runtime | Model |`,
+            `|------|-------------|---------|-------|`,
+            ...rows,
+        ].join("\n");
+    }
+    /** Available environments table. */
+    buildAvailableEnvironments() {
+        const envs = this.options.availableEnvironments;
+        if (!envs || envs.length === 0) {
+            return "";
+        }
+        const rows = envs.map((e) => `| ${e.displayName} | ${e.adapterType} | ${e.status} | ${e.defaultRuntime || "—"} |`);
+        return [
+            `## Available Environments`,
+            ``,
+            `| Name | Adapter | Status | Runtime |`,
+            `|------|---------|--------|---------|`,
+            ...rows,
+        ].join("\n");
+    }
+    /** Orchestrator findings section with actual findings data. */
+    buildOrchestratorFindingsSection() {
+        if (!this.options.findingsContext) {
+            return "";
+        }
+        return this.options.findingsContext;
+    }
+    /** Trigger context describing why this invocation happened. */
+    buildTriggerContext() {
+        if (this.options.triggerMode === "resume") {
+            return [
+                `## Trigger Context`,
+                `You are being re-invoked after one or more child tasks completed. Review the task tree above for current statuses and decide what to do next.`,
+            ].join("\n");
+        }
+        return [
+            `## Trigger Context`,
+            `You are being invoked for the first time to orchestrate this workspace. Assess the current state, then decompose your task into subtasks.`,
+        ].join("\n");
+    }
+    /** Decomposition heuristics and guardrails. */
+    buildDecompositionGuidelines() {
+        return [
+            `## Decomposition Guidelines`,
+            ``,
+            `- Estimate task complexity before decomposing. Do not decompose simple tasks (under ~100 lines of code or touching fewer than 3 files).`,
+            `- Favor context-boundary decomposition over role-boundary decomposition: the agent implementing a feature should also write its tests.`,
+            `- Consider coordination cost vs. parallel benefit. Decomposition multiplies token usage by 3-10x.`,
+            `- Keep the number of direct subtasks reasonable (aim for 3-7 per parent).`,
+            `- Each subtask description must be self-contained — the child agent has no context beyond what you provide in the description.`,
+            `- Set dependencies between subtasks when ordering matters. Independent subtasks can run in parallel.`,
+            `- Grant decomposition rights (\`canDecompose: true\`) only to subtasks that genuinely need to coordinate further work.`,
+        ].join("\n");
+    }
+    /** Orchestrator-specific MCP tool documentation. */
+    buildOrchestratorTools() {
+        return [
+            `## Orchestrator Tools`,
+            ``,
+            `Use these tools on your \`grackle\` MCP server to coordinate work:`,
+            `- \`task_create\` — Create a subtask with title, description, dependencies, persona, and decomposition rights.`,
+            `- \`task_list\` — List all tasks in the workspace with their current statuses.`,
+            `- \`task_show\` — Show details of a specific task including its sessions and output.`,
+            `- \`task_start\` — Start a task (begins agent execution on the assigned environment).`,
+            `- \`task_complete\` — Signal that your task is complete.`,
+            `- \`finding_post\` — Share a discovery (architecture decisions, patterns, bugs) with other agents.`,
+            `- \`finding_list\` — List recent findings from all agents in this workspace.`,
+        ].join("\n");
+    }
+    /** Orchestrator-specific completion contract. */
+    buildOrchestratorCompletionContract() {
+        return [
+            `## Completion`,
+            `When all subtasks are complete and you have verified the results, use \`task_complete\` to signal your own completion. If any subtasks failed, decide whether to retry, reassign, or handle the failure before completing.`,
+        ].join("\n");
+    }
+    // ─── Leaf Sections (unchanged) ───────────────────────────
     /** Task title, description, and notes. */
     buildTaskContext() {
         const { title, description, notes } = this.options.task;
@@ -73,7 +292,7 @@ export class SystemPromptBuilder {
             `3. If the child failed or was interrupted, decide whether to retry, reassign, or handle the failure yourself.`,
         ].join("\n");
     }
-    /** Guidance on using findings. */
+    /** Guidance on using findings (leaf agents). */
     buildFindingsSection() {
         return [
             `## Findings`,

package/dist/system-prompt-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt-builder.js","sourceRoot":"","sources":["../src/system-prompt-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IACb,OAAO,CAAsB;IAE9C,YAAmB,OAA4B;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,+CAA+C;IACxC,KAAK;QACV,MAAM,QAAQ,GAAa,EAAE,CAAC;QAE9B,6CAA6C;QAC7C,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;YACvC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,CAAC,CAAC;YAC9C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,CAAC;YAC1C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC;YACzC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC,CAAC;QAC7C,CAAC;QAED,6BAA6B;QAC7B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAEnC,OAAO,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,0CAA0C;IAClC,gBAAgB;QACtB,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,IAAK,CAAC;QACzD,MAAM,KAAK,GAAG;YACZ,YAAY,KAAK,EAAE;YACnB,WAAW;SACZ,CAAC;QACF,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,IAAI,CAAC,sDAAsD,KAAK,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED,8CAA8C;IACtC,uBAAuB;QAC7B,OAAO;YACL,eAAe;YACf,sMAAsM;SACvM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,8CAA8C;IACtC,mBAAmB;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YAC9B,OAAO;gBACL,aAAa;gBACb,4OAA4O;aAC7O,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,CAAC;QACD,OAAO;YACL,aAAa;YACb,yEAAyE;SAC1E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,oCAAoC;IAC5B,kBAAkB;QACxB,OAAO;YACL,YAAY;YACZ,oHAAoH;YACpH,wEAAwE;YACxE,mGAAmG;YACnG,+GAA+G;SAChH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,kCAAkC;IAC1B,oBAAoB;QAC1B,OAAO;YACL,aAAa;YACb,kKAAkK;SACnK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,kCAAkC;IAC1B,YAAY;QAClB,OAAO,gDAAgD,CAAC;IAC1D,CAAC;CACF"}
+{"version":3,"file":"system-prompt-builder.js","sourceRoot":"","sources":["../src/system-prompt-builder.ts"],"names":[],"mappings":"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"}

package/dist/ws-bridge.d.ts

@@ -1,5 +1,12 @@
-import { WebSocketServer } from "ws";
+import { WebSocketServer, WebSocket } from "ws";
 import type { Server as HttpServer } from "node:http";
+import * as taskStore from "./task-store.js";
 /** Create a WebSocket server on top of an HTTP server that bridges JSON messages to gRPC operations. */
 export declare function createWsBridge(httpServer: HttpServer, verifyApiKey: (token: string) => boolean, validateCookie?: (cookieHeader: string) => boolean): WebSocketServer;
+/** Start a new agent session for a task. Returns an error message string on failure, undefined on success. */
+export declare function startTaskSession(ws: WebSocket | undefined, task: taskStore.TaskRow, options?: {
+    personaId?: string;
+    environmentId?: string;
+    notes?: string;
+}): Promise<string | undefined>;
 //# sourceMappingURL=ws-bridge.d.ts.map

package/dist/ws-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws-bridge.d.ts","sourceRoot":"","sources":["../src/ws-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAa,MAAM,IAAI,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AAiEtD,wGAAwG;AACxG,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,EACxC,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,GACjD,eAAe,CA6CjB"}
+{"version":3,"file":"ws-bridge.d.ts","sourceRoot":"","sources":["../src/ws-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AAetD,OAAO,KAAK,SAAS,MAAM,iBAAiB,CAAC;AAmD7C,wGAAwG;AACxG,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,EACxC,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,GACjD,eAAe,CA6CjB;AA0HD,8GAA8G;AAC9G,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,SAAS,GAAG,SAAS,EACzB,IAAI,EAAE,SAAS,CAAC,OAAO,EACvB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA6I7B"}

package/dist/ws-bridge.js

@@ -16,13 +16,14 @@ import { v4 as uuid } from "uuid";
 import { join } from "node:path";
 import { LOGS_DIR, SESSION_STATUS, TERMINAL_SESSION_STATUSES, TASK_STATUS, DEFAULT_MCP_PORT, ROOT_TASK_ID, eventTypeToString, } from "@grackle-ai/common";
 import { resolvePersona } from "./resolve-persona.js";
+import { fetchOrchestratorContext } from "./orchestrator-context.js";
 import * as settingsStore from "./settings-store.js";
 import { isAllowedSettingKey } from "./settings-store.js";
 import { grackleHome } from "./paths.js";
 import * as logWriter from "./log-writer.js";
 import { safeParseJsonArray } from "./json-helpers.js";
 import { logger } from "./logger.js";
-import { SystemPromptBuilder } from "./system-prompt-builder.js";
+import { SystemPromptBuilder, buildTaskPrompt } from "./system-prompt-builder.js";
 import { slugify } from "./utils/slugify.js";
 import { processEventStream } from "./event-processor.js";
 import * as processorRegistry from "./processor-registry.js";
@@ -119,6 +120,7 @@ async function autoProvisionEnvironment(ws, environmentId, env, logContext) {
     emit("environment.changed", {});
     try {
         const config = safeParseAdapterConfig(env.adapterConfig, environmentId);
+        config.defaultRuntime = env.defaultRuntime;
         const powerlineToken = env.powerlineToken || "";
         for await (const provEvent of reconnectOrProvision(environmentId, adapter, config, powerlineToken, !!env.bootstrapped)) {
             logger.info({ environmentId, stage: provEvent.stage, ...logContext }, "Auto-provision progress");
@@ -165,15 +167,8 @@ async function autoProvisionEnvironment(ws, environmentId, env, logContext) {
         return undefined;
     }
 }
-/**
- * Start a new agent session for a task. Handles environment lookup,
- * auto-provisioning, session creation, spawning, and completion wiring.
- *
- * Returns undefined on success (or if the failure was already reported
- * to the client via WS, e.g. provisioning errors), or an error message
- * string for failures that need the caller to surface to the client.
- */
-async function startTaskSession(ws, task, options) {
+/** Start a new agent session for a task. Returns an error message string on failure, undefined on success. */
+export async function startTaskSession(ws, task, options) {
     const workspace = task.workspaceId ? workspaceStore.getWorkspace(task.workspaceId) : undefined;
     if (task.workspaceId && !workspace) {
         logger.warn({ taskId: task.id }, "startTaskSession failed: workspace not found");
@@ -185,11 +180,17 @@ async function startTaskSession(ws, task, options) {
         logger.warn({ taskId: task.id, environmentId }, "startTaskSession failed: environment not found");
         return `Environment not found: ${environmentId}`;
     }
-    const conn = await autoProvisionEnvironment(ws, environmentId, env, {
-        taskId: task.id,
-    });
+    let conn;
+    if (ws) {
+        conn = await autoProvisionEnvironment(ws, environmentId, env, {
+            taskId: task.id,
+        });
+    }
+    else {
+        conn = adapterManager.getConnection(environmentId) ?? undefined;
+    }
     if (!conn) {
-        return undefined;
+        return ws ? undefined : `Environment not connected: ${environmentId}`;
     }
     // Resolve persona via cascade (request → task → workspace → app default)
     let resolved;
@@ -205,16 +206,19 @@ async function startTaskSession(ws, task, options) {
     const freshTask = taskStore.getTask(task.id) || task;
     // For the root/System task, use the user's chat message (passed as notes)
     // as the initial prompt instead of the task title "System".
-    // For regular tasks, the task title IS the prompt.
-    const initialPrompt = freshTask.id === ROOT_TASK_ID
+    // For regular tasks, build the prompt from title + description.
+    const taskPrompt = freshTask.id === ROOT_TASK_ID
         ? (options?.notes || "")
-        : freshTask.title;
+        : buildTaskPrompt(freshTask.title, freshTask.description, options?.notes);
+    const orchestratorCtx = freshTask.canDecompose && freshTask.depth <= 1
+        ? fetchOrchestratorContext(freshTask.workspaceId || "") : undefined;
     const systemContext = new SystemPromptBuilder({
         task: { title: freshTask.title, description: freshTask.description, notes: options?.notes || "" },
-        canDecompose: freshTask.canDecompose,
-        personaPrompt: systemPrompt,
+        taskId: freshTask.id, canDecompose: freshTask.canDecompose, personaPrompt: systemPrompt,
+        taskDepth: freshTask.depth, ...orchestratorCtx,
+        ...(orchestratorCtx && { triggerMode: "fresh" }),
     }).build();
-    sessionStore.createSession(sessionId, environmentId, runtime, initialPrompt || freshTask.title, model, logPath, freshTask.id, resolved.personaId);
+    sessionStore.createSession(sessionId, environmentId, runtime, freshTask.title, model, logPath, freshTask.id, resolved.personaId);
     emit("task.started", {
         taskId: freshTask.id,
         sessionId,
@@ -245,7 +249,7 @@ async function startTaskSession(ws, task, options) {
     const powerlineReq = create(powerline.SpawnRequestSchema, {
         sessionId,
         runtime,
-        prompt: initialPrompt,
+        prompt: taskPrompt,
         model,
         maxTurns,
         branch: freshTask.branch,
@@ -266,7 +270,7 @@ async function startTaskSession(ws, task, options) {
         workspaceId: freshTask.workspaceId ?? undefined,
         taskId: freshTask.id,
         systemContext,
-        prompt: initialPrompt,
+        prompt: taskPrompt,
     });
     return undefined;
 }
@@ -1285,6 +1289,7 @@ async function handleMessage(ws, msg, subscriptions) {
             (async () => {
                 try {
                     const config = safeParseAdapterConfig(env.adapterConfig, environmentId);
+                    config.defaultRuntime = env.defaultRuntime;
                     const powerlineToken = env.powerlineToken || "";
                     for await (const event of reconnectOrProvision(environmentId, adapter, config, powerlineToken, !!env.bootstrapped)) {
                         logger.info({ environmentId, stage: event.stage, message: event.message }, "Provision progress");