@phuetz/code-buddy 1.1.0 → 1.2.0

package/dist/goals/goal-decomposer.js

@@ -0,0 +1,293 @@
+import { parseJsonResponse } from '../utils/llm-retry.js';
+const DEFAULT_PLAN_MAX_TOKENS = 4096;
+const DEFAULT_PLAN_TIMEOUT_MS = 45_000;
+const MAX_TOP_LEVEL_TASKS = 8;
+const MAX_SUBTASKS_PER_TASK = 6;
+const MAX_CRITERIA_PER_ITEM = 6;
+const MAX_NOTES = 6;
+const MAX_FIELD_LENGTH = 500;
+export function shouldAutoDecomposeGoal(goal) {
+    const text = goal.trim().toLowerCase();
+    if (!text)
+        return false;
+    if (text.length >= 140)
+        return true;
+    const structuralHints = [
+        /\bthen\b/,
+        /\bfinally\b/,
+        /\bfirst\b/,
+        /\bsecond\b/,
+        /\bthird\b/,
+        /\bstep\s+\d+\b/,
+        /\bsous[-\s]?t[aâ]che/,
+        /\bsub[-\s]?task/,
+        /\bdecompos/,
+        /\bplan\b/,
+        /\bdag\b/,
+        /\bparallel/,
+        /\bimpl[eé]ment.*test/,
+        /\bresearch.*implement/,
+    ];
+    return structuralHints.some((pattern) => pattern.test(text));
+}
+export async function decomposeGoal(goal, client, options = {}) {
+    const messages = [
+        {
+            role: 'system',
+            content: 'You are a Hermes-style kanban orchestrator. Decompose a user goal into ' +
+                'a durable task graph before execution. Extract independent work lanes, ' +
+                'link only true dependencies, and add concrete acceptance criteria. ' +
+                'Return only valid JSON.',
+        },
+        {
+            role: 'user',
+            content: buildGoalDecompositionPrompt(goal),
+        },
+    ];
+    const response = await withTimeout(client.chat(messages, [], {
+        ...(options.model ? { model: options.model } : {}),
+        maxTokens: options.maxTokens ?? DEFAULT_PLAN_MAX_TOKENS,
+        temperature: 0,
+    }), options.timeoutMs ?? DEFAULT_PLAN_TIMEOUT_MS);
+    const raw = response.choices?.[0]?.message?.content ?? '';
+    return parseGoalPlan(raw, goal);
+}
+export function parseGoalPlan(raw, originalGoal = '') {
+    if (!raw.trim())
+        return null;
+    let parsed;
+    try {
+        parsed = parseJsonResponse(raw);
+    }
+    catch {
+        return null;
+    }
+    return normalizeGoalPlan(parsed, originalGoal);
+}
+export function normalizeGoalPlan(raw, originalGoal = '') {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const record = raw;
+    const rawTasks = Array.isArray(record.tasks) ? record.tasks : [];
+    if (rawTasks.length === 0)
+        return null;
+    const tasks = [];
+    const seenIds = new Set();
+    const rawById = new Map();
+    for (let i = 0; i < rawTasks.length && tasks.length < MAX_TOP_LEVEL_TASKS; i++) {
+        const rawTask = rawTasks[i];
+        if (!rawTask || typeof rawTask !== 'object' || Array.isArray(rawTask))
+            continue;
+        const taskRecord = rawTask;
+        const fallbackId = `T${tasks.length + 1}`;
+        const id = uniqueId(cleanId(taskRecord.id, fallbackId), seenIds);
+        const title = cleanText(taskRecord.title, `Task ${tasks.length + 1}`);
+        const description = cleanOptionalText(taskRecord.description);
+        const acceptanceCriteria = cleanCriteria(taskRecord, title);
+        const subtasks = cleanSubtasks(taskRecord.subtasks, id);
+        tasks.push({
+            id,
+            title,
+            ...(description ? { description } : {}),
+            acceptanceCriteria,
+            dependsOn: [],
+            subtasks,
+        });
+        rawById.set(id, taskRecord);
+    }
+    if (tasks.length === 0)
+        return null;
+    const validIds = new Set(tasks.map((task) => task.id));
+    for (const task of tasks) {
+        const taskRecord = rawById.get(task.id);
+        task.dependsOn = cleanDependsOn(taskRecord, task.id, validIds);
+    }
+    const summary = cleanText(record.summary, originalGoal ? `Decomposed plan for: ${originalGoal}` : 'Decomposed goal plan');
+    const notes = cleanStringArray(record.notes).slice(0, MAX_NOTES);
+    return {
+        summary,
+        tasks,
+        ...(notes.length ? { notes } : {}),
+    };
+}
+export function goalPlanToCriteria(plan, maxCriteria = 30) {
+    if (!plan)
+        return [];
+    const criteria = [];
+    for (const task of plan.tasks) {
+        const depends = task.dependsOn.length ? ` after ${task.dependsOn.join(', ')}` : '';
+        const taskCriteria = task.acceptanceCriteria.length
+            ? task.acceptanceCriteria.join('; ')
+            : task.description || task.title;
+        criteria.push(`${task.id} ${task.title}${depends}: ${taskCriteria}`);
+        for (const subtask of task.subtasks) {
+            const subtaskCriteria = subtask.acceptanceCriteria.length
+                ? subtask.acceptanceCriteria.join('; ')
+                : subtask.description || subtask.title;
+            criteria.push(`${subtask.id} ${task.title} / ${subtask.title}: ${subtaskCriteria}`);
+            if (criteria.length >= maxCriteria)
+                return criteria;
+        }
+        if (criteria.length >= maxCriteria)
+            return criteria;
+    }
+    return criteria;
+}
+export function formatGoalPlan(plan) {
+    const lines = [`Plan: ${plan.summary}`, `Tasks: ${plan.tasks.length}`];
+    for (const task of plan.tasks) {
+        lines.push(`- ${task.id}: ${task.title}`);
+        if (task.dependsOn.length) {
+            lines.push(`  depends on: ${task.dependsOn.join(', ')}`);
+        }
+        if (task.acceptanceCriteria.length) {
+            lines.push(`  acceptance: ${task.acceptanceCriteria.join('; ')}`);
+        }
+        for (const subtask of task.subtasks) {
+            lines.push(`  - ${subtask.id}: ${subtask.title}`);
+            if (subtask.acceptanceCriteria.length) {
+                lines.push(`    acceptance: ${subtask.acceptanceCriteria.join('; ')}`);
+            }
+        }
+    }
+    if (plan.notes?.length) {
+        lines.push(`Notes: ${plan.notes.join('; ')}`);
+    }
+    return lines.join('\n');
+}
+function buildGoalDecompositionPrompt(goal) {
+    return `Goal:
+${goal}
+
+Decompose this goal into a task graph with sub-subtasks.
+
+Use this exact JSON shape:
+{
+  "summary": "one sentence",
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "short task title",
+      "description": "what this task does",
+      "dependsOn": [],
+      "acceptanceCriteria": ["specific evidence required"],
+      "subtasks": [
+        {
+          "id": "T1.1",
+          "title": "short subtask title",
+          "description": "what this subtask does",
+          "acceptanceCriteria": ["specific evidence required"]
+        }
+      ]
+    }
+  ],
+  "notes": ["optional orchestration notes"]
+}
+
+Rules:
+1. Create 2-8 top-level tasks only when the goal is genuinely multi-step; otherwise return one task.
+2. Treat independent lanes as parallel tasks with empty dependsOn.
+3. Add dependsOn only when a task cannot start until another task's output exists.
+4. Include final integration/review tasks only when useful, with dependsOn set in the original task object.
+5. Each top-level task should include 1-5 concrete subtasks when there is real substructure.
+6. Acceptance criteria must be observable evidence, not generic "done" statements.
+7. Return only the JSON object.`;
+}
+function cleanSubtasks(raw, parentId) {
+    if (!Array.isArray(raw))
+        return [];
+    const subtasks = [];
+    const seenIds = new Set();
+    for (const item of raw) {
+        if (subtasks.length >= MAX_SUBTASKS_PER_TASK)
+            break;
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            continue;
+        const record = item;
+        const fallbackId = `${parentId}.${subtasks.length + 1}`;
+        const id = uniqueId(cleanId(record.id, fallbackId), seenIds);
+        const title = cleanText(record.title, `Subtask ${subtasks.length + 1}`);
+        const description = cleanOptionalText(record.description);
+        subtasks.push({
+            id,
+            title,
+            ...(description ? { description } : {}),
+            acceptanceCriteria: cleanCriteria(record, title),
+        });
+    }
+    return subtasks;
+}
+function cleanCriteria(record, fallbackTitle) {
+    const raw = record.acceptanceCriteria ??
+        record.criteria ??
+        record.acceptance ??
+        record.doneWhen;
+    const values = cleanStringArray(raw).slice(0, MAX_CRITERIA_PER_ITEM);
+    return values.length ? values : [`Evidence shows "${fallbackTitle}" is complete`];
+}
+function cleanDependsOn(record, ownId, validIds) {
+    if (!record)
+        return [];
+    const raw = record.dependsOn ?? record.dependencies ?? record.parents;
+    const seen = new Set();
+    return cleanStringArray(raw).filter((id) => {
+        if (id === ownId || !validIds.has(id) || seen.has(id))
+            return false;
+        seen.add(id);
+        return true;
+    });
+}
+function cleanId(raw, fallback) {
+    const text = typeof raw === 'string' ? raw.trim() : '';
+    const cleaned = text.replace(/[^a-zA-Z0-9_.-]/g, '').slice(0, 32);
+    return cleaned || fallback;
+}
+function uniqueId(id, seen) {
+    if (!seen.has(id)) {
+        seen.add(id);
+        return id;
+    }
+    let suffix = 2;
+    while (seen.has(`${id}-${suffix}`))
+        suffix += 1;
+    const unique = `${id}-${suffix}`;
+    seen.add(unique);
+    return unique;
+}
+function cleanText(raw, fallback) {
+    const text = typeof raw === 'string' ? raw.trim() : '';
+    return (text || fallback).slice(0, MAX_FIELD_LENGTH);
+}
+function cleanOptionalText(raw) {
+    const text = typeof raw === 'string' ? raw.trim() : '';
+    return text ? text.slice(0, MAX_FIELD_LENGTH) : undefined;
+}
+function cleanStringArray(raw) {
+    const values = Array.isArray(raw) ? raw : typeof raw === 'string' ? [raw] : [];
+    const seen = new Set();
+    const cleaned = [];
+    for (const value of values) {
+        const text = String(value).trim().replace(/\s+/g, ' ').slice(0, MAX_FIELD_LENGTH);
+        if (!text || seen.has(text))
+            continue;
+        seen.add(text);
+        cleaned.push(text);
+    }
+    return cleaned;
+}
+async function withTimeout(promise, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`goal decomposition timed out after ${ms}ms`)), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=goal-decomposer.js.map

package/dist/goals/goal-judge-client.d.ts

@@ -0,0 +1,15 @@
+import { CodeBuddyClient } from '../codebuddy/client.js';
+export interface GoalJudgeProviderInfo {
+    apiKey: string;
+    baseURL?: string;
+    providerLabel?: string;
+}
+export interface GoalJudgeClientLike {
+    getCurrentModel?: () => string | undefined;
+}
+export declare function isChatGptJudgeModel(model: string | undefined): boolean;
+export declare function isChatGptProvider(provider: GoalJudgeProviderInfo | undefined): boolean;
+export declare function shouldUseStandaloneChatGptJudge(judgeModel: string | undefined, agentProvider?: GoalJudgeProviderInfo, currentClient?: GoalJudgeClientLike | null): boolean;
+export declare function createStandaloneChatGptJudgeClient(judgeModel: string): Promise<CodeBuddyClient>;
+export declare function resolveGoalJudgeClient<T extends GoalJudgeClientLike | null>(currentClient: T, judgeModel: string | undefined, agentProvider?: GoalJudgeProviderInfo): Promise<T | CodeBuddyClient>;
+export declare function resolveGoalJudgeClientFailOpen<T extends GoalJudgeClientLike | null>(currentClient: T, judgeModel: string | undefined, agentProvider?: GoalJudgeProviderInfo): Promise<T | CodeBuddyClient | null>;

package/dist/goals/goal-judge-client.js

@@ -0,0 +1,45 @@
+import { CHATGPT_OAUTH_SENTINEL, CHATGPT_RESPONSES_BASE_URL, CodeBuddyClient, } from '../codebuddy/client.js';
+export function isChatGptJudgeModel(model) {
+    const normalized = model?.trim().toLowerCase() ?? '';
+    return normalized === 'gpt-5.5' || normalized.startsWith('gpt-5.5-');
+}
+export function isChatGptProvider(provider) {
+    if (!provider)
+        return false;
+    return (provider.apiKey === CHATGPT_OAUTH_SENTINEL ||
+        provider.baseURL?.includes('chatgpt.com/backend-api/codex') === true ||
+        provider.providerLabel?.toLowerCase().includes('chatgpt') === true);
+}
+export function shouldUseStandaloneChatGptJudge(judgeModel, agentProvider, currentClient) {
+    if (!isChatGptJudgeModel(judgeModel))
+        return false;
+    if (isChatGptProvider(agentProvider))
+        return false;
+    const currentModel = currentClient?.getCurrentModel?.();
+    return !isChatGptJudgeModel(currentModel);
+}
+export async function createStandaloneChatGptJudgeClient(judgeModel) {
+    const { hasCodexCredentials } = await import('../providers/codex-oauth.js');
+    if (!hasCodexCredentials()) {
+        throw new Error('ChatGPT judge model gpt-5.5 requires `buddy login chatgpt` first.');
+    }
+    return new CodeBuddyClient(CHATGPT_OAUTH_SENTINEL, judgeModel, CHATGPT_RESPONSES_BASE_URL);
+}
+export async function resolveGoalJudgeClient(currentClient, judgeModel, agentProvider) {
+    if (judgeModel && shouldUseStandaloneChatGptJudge(judgeModel, agentProvider, currentClient)) {
+        return createStandaloneChatGptJudgeClient(judgeModel);
+    }
+    return currentClient;
+}
+export async function resolveGoalJudgeClientFailOpen(currentClient, judgeModel, agentProvider) {
+    if (judgeModel && shouldUseStandaloneChatGptJudge(judgeModel, agentProvider, currentClient)) {
+        try {
+            return await createStandaloneChatGptJudgeClient(judgeModel);
+        }
+        catch {
+            return null;
+        }
+    }
+    return currentClient;
+}
+//# sourceMappingURL=goal-judge-client.js.map

package/dist/goals/goal-judge.d.ts

@@ -23,6 +23,8 @@ export interface GoalJudgeParams {
     subgoals?: string[];
     /** Override the judge model (config `goals.judgeModel`). Empty → client default. */
     model?: string;
+    /** Optional per-call cap for judge output. */
+    maxTokens?: number;
     timeoutMs?: number;
 }
 /** Signature used by GoalManager so tests can inject a fake judge. */

package/dist/goals/goal-judge.js

@@ -32,7 +32,11 @@ export async function judgeGoal(client, params) {
         const response = await withTimeout(client.chat([
             { role: 'system', content: JUDGE_SYSTEM_PROMPT },
             { role: 'user', content: prompt },
-        ], [], { ...(params.model ? { model: params.model } : {}), temperature: 0 }), timeoutMs);
+        ], [], {
+            ...(params.model ? { model: params.model } : {}),
+            ...(params.maxTokens ? { maxTokens: params.maxTokens } : {}),
+            temperature: 0,
+        }), timeoutMs);
         raw = response?.choices?.[0]?.message?.content ?? '';
         recordJudgeCost(client, params.model, response?.usage);
     }
@@ -92,12 +96,37 @@ export function parseJudgeResponse(raw) {
         };
     }
     const record = data;
-    const doneVal = record.done;
-    const done = typeof doneVal === 'string'
-        ? ['true', 'yes', '1', 'done'].includes(doneVal.trim().toLowerCase())
-        : Boolean(doneVal);
+    const parsedDone = parseDoneField(record.done);
+    if (!parsedDone.ok) {
+        return {
+            verdict: 'continue',
+            reason: `judge reply had invalid done field: ${truncateText(raw, 200)}`,
+            parseFailed: true,
+        };
+    }
     const reason = String(record.reason ?? '').trim() || 'no reason provided';
-    return { verdict: done ? 'done' : 'continue', reason, parseFailed: false };
+    return { verdict: parsedDone.done ? 'done' : 'continue', reason, parseFailed: false };
+}
+function parseDoneField(value) {
+    if (typeof value === 'boolean')
+        return { ok: true, done: value };
+    if (typeof value === 'number') {
+        if (value === 1)
+            return { ok: true, done: true };
+        if (value === 0)
+            return { ok: true, done: false };
+        return { ok: false };
+    }
+    if (typeof value !== 'string')
+        return { ok: false };
+    const normalized = value.trim().toLowerCase();
+    if (['true', 'yes', '1', 'done'].includes(normalized)) {
+        return { ok: true, done: true };
+    }
+    if (['false', 'no', '0', 'continue', 'not_done', 'not done'].includes(normalized)) {
+        return { ok: true, done: false };
+    }
+    return { ok: false };
 }
 /** Judge calls consume real tokens — record them in the session cost ledger. */
 function recordJudgeCost(client, modelOverride, usage) {

package/dist/goals/goal-loop.d.ts

@@ -7,11 +7,23 @@
  * back into the session. Safe to call when no goal is set — returns fast.
  */
 import { CodeBuddyClient } from '../codebuddy/client.js';
+import type { GoalStatus, GoalVerdict } from './goal-state.js';
 export interface GoalTurnOutcome {
     /** User-visible status line (✓ / ⏸ / ↻) to append to chat history. */
     message?: string;
     /** When set, the caller should auto-submit this as the next user message. */
     continuationPrompt?: string;
+    /**
+     * Structured snapshot for host UIs (e.g. the Cowork goal banner). Mirrors the
+     * post-decision GoalState so the renderer can show turn progress + verdict
+     * without re-reading goal storage. Absent fields when no goal is active.
+     */
+    goalText?: string;
+    status?: GoalStatus;
+    turnsUsed?: number;
+    maxTurns?: number;
+    lastVerdict?: GoalVerdict;
+    lastReason?: string;
 }
 export interface GoalAfterTurnOptions {
     client: CodeBuddyClient | null;
@@ -19,5 +31,7 @@ export interface GoalAfterTurnOptions {
     lastResponse: string;
     /** True when the turn was user-interrupted (Esc). */
     interrupted: boolean;
+    /** Optional goal-state key for host surfaces with their own session ids. */
+    sessionKey?: string;
 }
 export declare function maybeContinueGoalAfterTurn(options: GoalAfterTurnOptions): Promise<GoalTurnOutcome | null>;

package/dist/goals/goal-loop.js

@@ -7,13 +7,14 @@
  * back into the session. Safe to call when no goal is set — returns fast.
  */
 import { logger } from '../utils/logger.js';
+import { decomposeGoal, shouldAutoDecomposeGoal } from './goal-decomposer.js';
 import { judgeGoal } from './goal-judge.js';
 import { getGoalManager, resolveGoalsConfig } from './goal-manager.js';
 // The executor appends a per-turn usage footer ("[tokens: … | cost: …]") as a
 // final content chunk; strip it so the judge sees only substantive output.
 const USAGE_FOOTER_RE = /\n?\[tokens: [^\]]*\]\s*$/;
 export async function maybeContinueGoalAfterTurn(options) {
-    const manager = getGoalManager();
+    const manager = getGoalManager(options.sessionKey);
     if (!manager.isActive())
         return null;
     // If the turn was user-interrupted, auto-pause instead of judging: the
@@ -28,6 +29,7 @@ export async function maybeContinueGoalAfterTurn(options) {
         }
         return {
             message: '⏸ Goal paused — turn was interrupted. Use /goal resume to continue, or /goal clear to stop.',
+            ...goalSnapshot(manager),
         };
     }
     const lastResponse = options.lastResponse.replace(USAGE_FOOTER_RE, '').trim();
@@ -36,16 +38,18 @@ export async function maybeContinueGoalAfterTurn(options) {
     if (!lastResponse)
         return null;
     const config = resolveGoalsConfig();
+    await maybeAttachGoalPlan(manager, options.client, config.plannerModel);
     const decision = await manager.evaluateAfterTurn(lastResponse, {
         judge: params => judgeGoal(options.client, {
             ...params,
             ...(config.judgeModel ? { model: config.judgeModel } : {}),
+            maxTokens: config.judgeMaxTokens,
             timeoutMs: config.judgeTimeoutMs,
         }),
     });
     if (decision.verdict === 'inactive')
         return null;
-    const outcome = {};
+    const outcome = { ...goalSnapshot(manager) };
     if (decision.message)
         outcome.message = decision.message;
     if (decision.shouldContinue && decision.continuationPrompt) {
@@ -53,4 +57,45 @@ export async function maybeContinueGoalAfterTurn(options) {
     }
     return outcome;
 }
+/**
+ * Structured per-session goal snapshot for host UIs. Reads the manager's
+ * post-decision state; returns an empty object when no state is present so
+ * spreading it is always safe.
+ */
+function goalSnapshot(manager) {
+    const s = manager.state;
+    if (!s)
+        return {};
+    return {
+        goalText: s.goal,
+        status: s.status,
+        turnsUsed: s.turnsUsed,
+        maxTurns: s.maxTurns,
+        ...(s.lastVerdict ? { lastVerdict: s.lastVerdict } : {}),
+        ...(s.lastReason ? { lastReason: s.lastReason } : {}),
+    };
+}
+async function maybeAttachGoalPlan(manager, client, model) {
+    const state = manager.state;
+    if (!state || state.goalPlan || state.goalPlanAttempted)
+        return;
+    if (!client || !shouldAutoDecomposeGoal(state.goal))
+        return;
+    try {
+        const plan = await decomposeGoal(state.goal, client, {
+            ...(model ? { model } : {}),
+        });
+        if (plan) {
+            manager.attachGoalPlan(plan);
+        }
+        else {
+            manager.markGoalPlanAttempted('planner returned no usable task graph');
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        manager.markGoalPlanAttempted(message);
+        logger.debug('goal decomposition failed', { error: message });
+    }
+}
 //# sourceMappingURL=goal-loop.js.map

package/dist/goals/goal-manager.d.ts

@@ -9,6 +9,7 @@
  * the manager (and its tests) never touch a provider.
  */
 import { GoalJudgeFn } from './goal-judge.js';
+import type { GoalPlan } from './goal-decomposer.js';
 import { GoalState, GoalStatus, GoalVerdict } from './goal-state.js';
 import { GoalStore } from './goal-store.js';
 export interface GoalTurnDecision {
@@ -23,6 +24,7 @@ export interface GoalTurnDecision {
 export interface GoalsConfig {
     maxTurns: number;
     judgeModel: string;
+    plannerModel: string;
     judgeMaxTokens: number;
     judgeTimeoutMs: number;
 }
@@ -38,7 +40,11 @@ export declare class GoalManager {
     statusLine(): string;
     set(goal: string, options?: {
         maxTurns?: number;
+        goalPlan?: GoalPlan;
+        goalPlanAttempted?: boolean;
     }): GoalState;
+    attachGoalPlan(plan: GoalPlan): GoalState | null;
+    markGoalPlanAttempted(error?: string): GoalState | null;
     pause(reason?: string): GoalState | null;
     resume(options?: {
         resetBudget?: boolean;