clementine-agent 1.18.205 → 1.18.206

package/dist/agent/agent-definitions.js

@@ -61,7 +61,7 @@ const RESEARCHER_PROMPT = [
     '',
     '## Output discipline',
     '',
-    'Return a ONE-PARAGRAPH summary in the format the parent specified. Never raw tool output, never full lists, never unbounded data dumps. If a tool returns 50KB of JSON, extract only the requested fields and discard the rest — your job is to compress.',
+    'Return a ONE-PARAGRAPH summary in the format the parent specified. Hard limit: 250 words unless the parent explicitly asks for a longer artifact. Never raw tool output, never full lists, never unbounded data dumps. If a tool returns 50KB of JSON, extract only the requested fields and discard the rest — your job is to compress.',
     '',
     'If you cannot find the requested data, say so in one line. Do not speculate.',
 ].join('\n');
@@ -106,6 +106,8 @@ const DISCOVERY_PROMPT = [
     'Recommendation: <which path the orchestrator should fetch next, if any>',
     '```',
     '',
+    'Hard output limit: 250 words. Return decision-grade handoff only: paths, counts, sizes, and the next file/action the orchestrator should inspect. Do NOT return a full project report, long markdown excerpts, repeated file inventories, or narrative analysis. If the parent needs detail, point it at the exact file path to read next.',
+    '',
     'If nothing matches, say so in one line.',
     '',
     'You are bounded by max 15 turns. Use them wisely — list, scope, summarize, return.',

package/dist/agent/run-summary.d.ts

@@ -31,6 +31,9 @@ export interface RunSummary {
     failedSideEffects: SideEffectCall[];
     pendingSideEffects: SideEffectCall[];
     unknownEffectCalls: SideEffectCall[];
+    successfulDelegations: SideEffectCall[];
+    failedDelegations: SideEffectCall[];
+    pendingDelegations: SideEffectCall[];
     readOnlyCount: number;
     errors: Array<{
         runId: string;

package/dist/agent/run-summary.js

@@ -66,11 +66,23 @@ export function summarizeRunSideEffects(runIds, eventLog = new EventLog()) {
     const failedSideEffects = [];
     const pendingSideEffects = [];
     const unknownEffectCalls = [];
+    const successfulDelegations = [];
+    const failedDelegations = [];
+    const pendingDelegations = [];
     let readOnlyCount = 0;
     for (const call of events.filter(isToolCall)) {
         const verdict = classifyToolCall(call.toolName, asInput(call.toolInput));
         const result = resultForToolUse(events, call.toolUseId);
         const item = makeCall(call, result, verdict);
+        if (call.toolName === 'Agent') {
+            if (!result)
+                pendingDelegations.push(item);
+            else if (item.result?.successful)
+                successfulDelegations.push(item);
+            else
+                failedDelegations.push(item);
+            continue;
+        }
         if (verdict.kind === 'read_only') {
             readOnlyCount += 1;
             continue;
@@ -110,6 +122,9 @@ export function summarizeRunSideEffects(runIds, eventLog = new EventLog()) {
         failedSideEffects,
         pendingSideEffects,
         unknownEffectCalls,
+        successfulDelegations,
+        failedDelegations,
+        pendingDelegations,
         readOnlyCount,
         errors,
         ...(lastAssistantText ? { lastAssistantText } : {}),
@@ -120,7 +135,10 @@ export function hasOperationalActivity(summary) {
     return summary.successfulSideEffects.length > 0
         || summary.failedSideEffects.length > 0
         || summary.pendingSideEffects.length > 0
-        || summary.unknownEffectCalls.length > 0;
+        || summary.unknownEffectCalls.length > 0
+        || summary.successfulDelegations.length > 0
+        || summary.failedDelegations.length > 0
+        || summary.pendingDelegations.length > 0;
 }
 function toolKindLabel(toolName) {
     const lower = toolName.toLowerCase();
@@ -206,6 +224,41 @@ function recipientPreview(calls, max = 3) {
 function formatGroupedLines(prefix, calls) {
     return groupCounts(calls).map((group) => `- ${group.count} ${group.label} ${prefix}${recipientPreview(group.calls)}`);
 }
+function collectResultText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.map(collectResultText).filter(Boolean).join('\n');
+    if (!value || typeof value !== 'object')
+        return '';
+    const obj = value;
+    return ['text', 'content', 'result', 'message']
+        .map((key) => collectResultText(obj[key]))
+        .filter(Boolean)
+        .join('\n');
+}
+function extractAgentArchivePath(text) {
+    return text.match(/Full payload archived at `([^`]+)`/)?.[1]
+        ?? text.match(/Full output:\s*([^\n]+)/)?.[1]?.trim();
+}
+function extractAgentId(text) {
+    return text.match(/\bagentId:\s*([a-zA-Z0-9_-]+)/)?.[1];
+}
+function formatDelegationCall(call, status) {
+    const description = firstString(call.input.description, call.input.task, call.input.prompt)?.slice(0, 120);
+    const subagentType = firstString(call.input.subagent_type, call.input.subagentType);
+    const resultText = call.result ? collectResultText(call.result.raw) : '';
+    const agentId = extractAgentId(resultText);
+    const archivePath = extractAgentArchivePath(resultText);
+    const pieces = [
+        subagentType ? `${subagentType} subagent` : 'subagent',
+        status,
+        description ? `for "${description}"` : undefined,
+        agentId ? `agentId ${agentId}` : undefined,
+        archivePath ? `archive ${archivePath}` : undefined,
+    ].filter(Boolean);
+    return `- ${pieces.join(' · ')}`;
+}
 export function formatOverflowRecoveryMessage(summary) {
     const lines = [
         'That run hit the context limit after some work had already happened.',
@@ -216,12 +269,28 @@ export function formatOverflowRecoveryMessage(summary) {
         lines.push(...formatGroupedLines('completed', summary.successfulSideEffects));
         lines.push('');
     }
-    if (summary.failedSideEffects.length > 0 || summary.pendingSideEffects.length > 0 || summary.unknownEffectCalls.length > 0) {
+    if (summary.successfulDelegations.length > 0) {
+        lines.push('Delegated work completed before overflow:');
+        for (const call of summary.successfulDelegations.slice(0, 5))
+            lines.push(formatDelegationCall(call, 'completed'));
+        if (summary.successfulDelegations.length > 5)
+            lines.push(`- ...and ${summary.successfulDelegations.length - 5} more completed subagent calls`);
+        lines.push('');
+    }
+    if (summary.failedSideEffects.length > 0
+        || summary.pendingSideEffects.length > 0
+        || summary.unknownEffectCalls.length > 0
+        || summary.failedDelegations.length > 0
+        || summary.pendingDelegations.length > 0) {
         lines.push('Needs attention:');
         if (summary.failedSideEffects.length > 0)
             lines.push(...formatGroupedLines('failed', summary.failedSideEffects));
         if (summary.pendingSideEffects.length > 0)
             lines.push(...formatGroupedLines('started, no confirmation', summary.pendingSideEffects));
+        for (const call of summary.failedDelegations.slice(0, 5))
+            lines.push(formatDelegationCall(call, 'failed'));
+        for (const call of summary.pendingDelegations.slice(0, 5))
+            lines.push(formatDelegationCall(call, 'started, no confirmation'));
         if (summary.unknownEffectCalls.length > 0)
             lines.push(`- ${summary.unknownEffectCalls.length} tool call(s) had unknown external effect`);
         lines.push('');
@@ -261,6 +330,12 @@ export function buildContinuationPrompt(summary, originalRequest) {
             lines.push(`- ...and ${summary.successfulSideEffects.length - 80} more completed side effects in the event log.`);
         lines.push('');
     }
+    if (summary.successfulDelegations.length > 0) {
+        lines.push('Completed delegated work. Do not repeat discovery/research already done unless the archive is insufficient:');
+        for (const call of summary.successfulDelegations.slice(0, 20))
+            lines.push(formatDelegationCall(call, 'completed'));
+        lines.push('');
+    }
     if (summary.failedSideEffects.length > 0) {
         lines.push('Failed side effects that may need retry or reconciliation:');
         for (const call of summary.failedSideEffects.slice(0, 30))

package/dist/agent/tool-output-guard.d.ts

@@ -80,6 +80,8 @@ export interface GuardRunStats {
 export declare function estimateBytes(value: unknown): number;
 interface CompressionContext {
     toolName: string;
+    toolUseId?: string;
+    toolInput?: unknown;
     archivePath: string | null;
     cap: number;
 }

package/dist/agent/tool-output-guard.js

@@ -117,6 +117,101 @@ function tryListShrink(value, ctx) {
     }
     return null;
 }
+function collectTextFragments(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap((item) => collectTextFragments(item));
+    if (!value || typeof value !== 'object')
+        return [];
+    const obj = value;
+    const out = [];
+    for (const key of ['text', 'content', 'result', 'message']) {
+        const v = obj[key];
+        if (typeof v === 'string')
+            out.push(v);
+        else if (Array.isArray(v) || (v && typeof v === 'object'))
+            out.push(...collectTextFragments(v));
+    }
+    return out;
+}
+function objectField(value, key) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? typeof value[key] === 'string'
+            ? String(value[key]).trim()
+            : undefined
+        : undefined;
+}
+function extractAgentId(text) {
+    return text.match(/\bagentId:\s*([a-zA-Z0-9_-]+)/)?.[1];
+}
+function extractUsageLine(text) {
+    const match = text.match(/<usage>[\s\S]*?(?:<\/usage>|$)/);
+    return match?.[0]?.replace(/\s+/g, ' ').trim().slice(0, 220);
+}
+function stripAgentBoilerplate(text) {
+    return text
+        .replace(/agentId:\s*[a-zA-Z0-9_-]+[\s\S]*$/i, '')
+        .replace(/<usage>[\s\S]*$/i, '')
+        .replace(/^\s*(perfect|great|okay|ok)[.!]?\s+now\s+i\s+have[^\n]*\n+/i, '')
+        .trim();
+}
+function compactMarkdownLines(text) {
+    const lines = stripAgentBoilerplate(text)
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && line !== '---' && line !== '```');
+    const keep = [];
+    for (const line of lines) {
+        if (keep.length >= 26)
+            break;
+        if (/^#{1,4}\s/.test(line) || /^[-*]\s/.test(line) || /^\d+\.\s/.test(line) || /^[A-Z][^:]{2,60}:/.test(line)) {
+            keep.push(line);
+            continue;
+        }
+        if (keep.length < 8 && line.length <= 220)
+            keep.push(line);
+    }
+    return keep.join('\n');
+}
+function fitUnderBytes(text, maxBytes) {
+    if (estimateBytes(text) <= maxBytes)
+        return text;
+    const marker = '\n\n[...compact handoff truncated; read the archived Agent result for full detail.]';
+    let head = text.slice(0, Math.max(200, maxBytes - estimateBytes(marker) - 200));
+    while (head.length > 200 && estimateBytes(head + marker) > maxBytes) {
+        head = head.slice(0, Math.floor(head.length * 0.9));
+    }
+    return `${head.trimEnd()}${marker}`;
+}
+function tryAgentShrink(value, ctx) {
+    if (ctx.toolName !== 'Agent')
+        return null;
+    const fragments = collectTextFragments(value);
+    const text = fragments.join('\n\n').trim();
+    if (!text)
+        return null;
+    const subagentType = objectField(ctx.toolInput, 'subagent_type');
+    const description = objectField(ctx.toolInput, 'description');
+    const agentId = extractAgentId(text);
+    const usage = extractUsageLine(text);
+    const summary = compactMarkdownLines(text);
+    const archive = archiveHint(ctx, 'full Agent result');
+    const lines = [
+        '[Clementine compacted this Agent result to protect the parent chat context.]',
+        subagentType ? `Subagent: ${subagentType}` : undefined,
+        description ? `Task: ${description}` : undefined,
+        agentId ? `agentId: ${agentId}` : undefined,
+        usage,
+        archive,
+        '',
+        'Decision-grade handoff:',
+        summary || fitUnderBytes(stripAgentBoilerplate(text), Math.max(1_000, Math.floor(ctx.cap * 0.6))),
+        '',
+        'Use this handoff to continue. Read the archived result only if the missing detail is necessary.',
+    ].filter((line) => typeof line === 'string' && line.length > 0);
+    return fitUnderBytes(lines.join('\n'), ctx.cap);
+}
 function shrinkArray(arr, ctx) {
     if (arr.length <= 6) {
         // Don't trim short lists; the bloat is somewhere else (likely a fat body).
@@ -244,6 +339,19 @@ export function compressToolOutput(_toolName, rawOutput, ctx) {
     if (originalBytes <= ctx.cap) {
         return { output: rawOutput, bytesShed: 0, ceilingHit: false, passthrough: true };
     }
+    // Agent tool results are subagent handoffs to the parent orchestrator.
+    // Preserve the decision-grade summary and archive the full result instead
+    // of letting a verbose report refill the parent context after compaction.
+    const agentShrunk = tryAgentShrink(rawOutput, ctx);
+    if (agentShrunk !== null) {
+        const bytes = estimateBytes(agentShrunk);
+        return {
+            output: agentShrunk,
+            bytesShed: Math.max(0, originalBytes - bytes),
+            ceilingHit: originalBytes > ctx.cap * 2,
+            passthrough: false,
+        };
+    }
     // Pass 1: list-shape shrink (preserves structure).
     const shrunk1 = tryListShrink(rawOutput, ctx);
     if (shrunk1 !== null) {
@@ -294,7 +402,7 @@ export function buildGuardHooks(opts) {
         const toolUseId = String(toolUseID ?? evt.tool_use_id ?? 'unknown');
         const rawOutput = evt.tool_response;
         stats.inspected += 1;
-        const usageRatio = opts.usageRatio ? safeRatio(opts.usageRatio) : 0;
+        const usageRatio = Math.max(opts.usageRatio ? safeRatio(opts.usageRatio) : 0, stats.compactions > 0 ? 0.75 : 0);
         const { softCap } = resolveCap(toolName, config, usageRatio);
         const originalBytes = estimateBytes(rawOutput);
         if (originalBytes <= softCap) {
@@ -307,6 +415,7 @@ export function buildGuardHooks(opts) {
         const archivePath = archivePayload(opts.archiveBaseDir ?? BASE_DIR, opts.runId, toolUseId, toolName, rawOutput);
         const outcome = compressToolOutput(toolName, rawOutput, {
             toolName,
+            toolInput: evt.tool_input,
             toolUseId,
             archivePath,
             cap: softCap,

package/dist/config.js

@@ -552,7 +552,10 @@ export const TOOL_OUTPUT_GUARD = {
     softLimitBytes: getEnvOrJsonNumber('TOOL_OUTPUT_GUARD_SOFT_BYTES', json.toolOutputGuard?.softLimitBytes, 30_000),
     hardLimitBytes: getEnvOrJsonNumber('TOOL_OUTPUT_GUARD_HARD_BYTES', json.toolOutputGuard?.hardLimitBytes, 200_000),
     adaptive: boolEnv('TOOL_OUTPUT_GUARD_ADAPTIVE', json.toolOutputGuard?.adaptive, true),
-    perTool: { ...(json.toolOutputGuard?.perTool ?? {}) },
+    // Agent results are especially dangerous: even a "medium" subagent report
+    // refills the parent orchestrator after compaction. Keep the handoff tight;
+    // the full result is archived by tool-output-guard.
+    perTool: { Agent: 4_000, ...(json.toolOutputGuard?.perTool ?? {}) },
 };
 export const DEFAULT_MODEL_TIER = (getEnvOrJson('DEFAULT_MODEL_TIER', json.models?.default, 'sonnet'));
 export const MODEL = MODELS[DEFAULT_MODEL_TIER] ?? MODELS.sonnet;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.205",
+  "version": "1.18.206",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",