sidecar-cli 0.1.4 → 0.1.5-beta.1

package/README.md

@@ -179,6 +179,29 @@ Artifacts:
 - `sidecar artifact add <path> [--kind file|doc|screenshot|other] [--note <text>] [--json]`
 - `sidecar artifact list [--json]`
 
+## Automatic prompt token budgeting
+
+When Sidecar compiles task prompts (`sidecar prompt compile` and run execution flows), it automatically applies a token budget to reduce context size without degrading execution quality.
+
+Current behavior:
+
+- Keeps required sections intact (task, objective, constraints, validation, definition of done).
+- Deduplicates repeated list items.
+- Trims only optional high-volume sections when needed (for example: in-scope lists, linked notes/decisions, long file lists).
+- Adds compact overflow lines such as `+ N more ... (see task packet for full list)`.
+
+Current defaults:
+
+- Target budget: ~1200 estimated tokens
+- Safety ceiling: ~1500 estimated tokens
+
+Prompt optimization data is included in compile output and stored on run records:
+
+- `prompt_tokens_estimated_before`
+- `prompt_tokens_estimated_after`
+- `prompt_budget_target`
+- `prompt_trimmed_sections`
+
 ## Example workflow
 
 ```bash

package/dist/cli.js

@@ -416,6 +416,7 @@ program
             'Documentation: https://usesidecar.dev/',
             ...(resolvedInstructions ? ['', `Loaded instructions.md from ${resolvedInstructions.sourceLabel}`] : []),
         ]);
+        maybePrintUpdateNotice();
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -974,11 +975,16 @@ prompt
             runner_type: compiled.runner_type,
             agent_role: compiled.agent_role,
             prompt_path: compiled.prompt_path,
+            prompt_optimization: compiled.prompt_optimization,
             preview: opts.preview ? compiled.prompt_markdown : null,
         }, [
             `Compiled prompt for ${compiled.task_id}.`,
             `Run: ${compiled.run_id}`,
             `Path: ${compiled.prompt_path}`,
+            `Prompt estimate: ${compiled.prompt_optimization.estimated_tokens_before} -> ${compiled.prompt_optimization.estimated_tokens_after} tokens (target ${compiled.prompt_optimization.budget_target})`,
+            ...(compiled.prompt_optimization.trimmed_sections.length > 0
+                ? [`Trimmed: ${compiled.prompt_optimization.trimmed_sections.join(', ')}`]
+                : []),
             ...(opts.preview ? ['', compiled.prompt_markdown] : []),
         ]);
     }
@@ -1353,7 +1359,6 @@ if (process.argv.length === 2) {
         console.log('');
     }
     program.outputHelp();
-    maybePrintUpdateNotice();
     process.exit(0);
 }
 if (process.argv[2] === 'run' &&
@@ -1369,4 +1374,3 @@ if (process.argv[2] === 'run' &&
     process.argv.splice(2, 1, 'run-exec');
 }
 program.parse(process.argv);
-maybePrintUpdateNotice();

package/dist/prompts/prompt-compiler.js

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { nowIso } from '../lib/format.js';
 import { getSidecarPaths } from '../lib/paths.js';
+const PROMPT_BUDGET_TARGET = 1200;
+const PROMPT_BUDGET_MAX = 1500;
 function section(title, lines) {
     return [`## ${title}`, ...lines, ''].join('\n');
 }
@@ -40,8 +42,44 @@ function runnerGuidance(runner) {
         'Provide a clear summary with validation and follow-up notes at the end.',
     ];
 }
-export function compilePromptMarkdown(input) {
-    const { task, run, runner, agentRole, linkedContext } = input;
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function dedupe(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items.map((v) => v.trim()).filter(Boolean)) {
+        const key = item.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(item);
+    }
+    return out;
+}
+function withOverflow(items, fullCount, label) {
+    const overflow = fullCount - items.length;
+    if (overflow <= 0)
+        return items;
+    return [...items, `+ ${overflow} more ${label} (see task packet for full list)`];
+}
+function buildPromptLists(input) {
+    const { task, linkedContext } = input;
+    return {
+        inScope: dedupe(task.scope.in_scope),
+        outOfScope: dedupe(task.scope.out_of_scope),
+        filesToRead: dedupe(task.implementation.files_to_read),
+        filesToAvoid: dedupe(task.implementation.files_to_avoid),
+        relatedDecisions: dedupe(linkedContext?.related_decisions ?? task.context.related_decisions),
+        relatedNotes: dedupe(linkedContext?.related_notes ?? task.context.related_notes),
+        technicalConstraints: dedupe(task.constraints.technical),
+        designConstraints: dedupe(task.constraints.design),
+        validationCommands: dedupe(task.execution.commands.validation),
+        definitionOfDone: dedupe(task.definition_of_done),
+    };
+}
+function renderPrompt(input, lists) {
+    const { task, run, runner, agentRole } = input;
     const lines = [];
     lines.push('# Sidecar Execution Brief');
     lines.push('');
@@ -59,26 +97,91 @@ export function compilePromptMarkdown(input) {
     ]));
     lines.push(section('Objective', [task.goal]));
     lines.push(section('Why this matters', [task.summary]));
-    lines.push(section('In scope', bullets(task.scope.in_scope)));
-    lines.push(section('Out of scope', bullets(task.scope.out_of_scope)));
-    lines.push(section('Read these first', bullets(task.implementation.files_to_read)));
-    lines.push(section('Avoid changing', bullets(task.implementation.files_to_avoid)));
-    const relatedDecisions = linkedContext?.related_decisions ?? task.context.related_decisions;
-    const relatedNotes = linkedContext?.related_notes ?? task.context.related_notes;
+    lines.push(section('In scope', bullets(lists.inScope)));
+    lines.push(section('Out of scope', bullets(lists.outOfScope)));
+    lines.push(section('Read these first', bullets(lists.filesToRead)));
+    lines.push(section('Avoid changing', bullets(lists.filesToAvoid)));
     lines.push(section('Linked context', [
-        ...bullets(relatedDecisions, '- no related decisions'),
-        ...bullets(relatedNotes, '- no related notes'),
+        ...bullets(lists.relatedDecisions, '- no related decisions'),
+        ...bullets(lists.relatedNotes, '- no related notes'),
     ]));
     lines.push(section('Constraints', [
-        ...bullets(task.constraints.technical, '- no technical constraints'),
-        ...bullets(task.constraints.design, '- no design constraints'),
+        ...bullets(lists.technicalConstraints, '- no technical constraints'),
+        ...bullets(lists.designConstraints, '- no design constraints'),
     ]));
-    lines.push(section('Validation', bullets(task.execution.commands.validation)));
-    lines.push(section('Definition of done', bullets(task.definition_of_done)));
+    lines.push(section('Validation', bullets(lists.validationCommands)));
+    lines.push(section('Definition of done', bullets(lists.definitionOfDone)));
     lines.push(section('Runner guidance', runnerGuidance(runner)));
     lines.push(section('Final response format', finalResponseFormat(runner)));
     return `${lines.join('\n').trim()}\n`;
 }
+function applyPromptBudget(input) {
+    const baseline = buildPromptLists(input);
+    const baselineMarkdown = renderPrompt(input, baseline);
+    const baselineTokens = estimateTokens(baselineMarkdown);
+    if (baselineTokens <= PROMPT_BUDGET_TARGET) {
+        return {
+            optimizedLists: baseline,
+            metadata: {
+                estimated_tokens_before: baselineTokens,
+                estimated_tokens_after: baselineTokens,
+                budget_target: PROMPT_BUDGET_TARGET,
+                budget_max: PROMPT_BUDGET_MAX,
+                trimmed_sections: [],
+            },
+        };
+    }
+    const optimized = {
+        ...baseline,
+        inScope: withOverflow(baseline.inScope.slice(0, 8), baseline.inScope.length, 'in-scope items'),
+        outOfScope: withOverflow(baseline.outOfScope.slice(0, 5), baseline.outOfScope.length, 'out-of-scope items'),
+        filesToRead: withOverflow(baseline.filesToRead.slice(0, 10), baseline.filesToRead.length, 'read-first files'),
+        filesToAvoid: withOverflow(baseline.filesToAvoid.slice(0, 5), baseline.filesToAvoid.length, 'avoid files'),
+        relatedDecisions: withOverflow(baseline.relatedDecisions.slice(0, 3), baseline.relatedDecisions.length, 'decisions'),
+        relatedNotes: withOverflow(baseline.relatedNotes.slice(0, 2), baseline.relatedNotes.length, 'notes'),
+    };
+    let optimizedMarkdown = renderPrompt(input, optimized);
+    let optimizedTokens = estimateTokens(optimizedMarkdown);
+    // Safety valve for unusually large tasks: preserve must-have sections and thin optional context further.
+    if (optimizedTokens > PROMPT_BUDGET_MAX) {
+        optimized.relatedDecisions = withOverflow(baseline.relatedDecisions.slice(0, 1), baseline.relatedDecisions.length, 'decisions');
+        optimized.relatedNotes = withOverflow([], baseline.relatedNotes.length, 'notes');
+        optimized.outOfScope = withOverflow(baseline.outOfScope.slice(0, 3), baseline.outOfScope.length, 'out-of-scope items');
+        optimized.filesToAvoid = withOverflow(baseline.filesToAvoid.slice(0, 3), baseline.filesToAvoid.length, 'avoid files');
+        optimizedMarkdown = renderPrompt(input, optimized);
+        optimizedTokens = estimateTokens(optimizedMarkdown);
+    }
+    const trimmedSections = [];
+    if (optimized.inScope.length < baseline.inScope.length)
+        trimmedSections.push('in_scope');
+    if (optimized.outOfScope.length < baseline.outOfScope.length)
+        trimmedSections.push('out_of_scope');
+    if (optimized.filesToRead.length < baseline.filesToRead.length)
+        trimmedSections.push('files_to_read');
+    if (optimized.filesToAvoid.length < baseline.filesToAvoid.length)
+        trimmedSections.push('files_to_avoid');
+    if (optimized.relatedDecisions.length < baseline.relatedDecisions.length)
+        trimmedSections.push('related_decisions');
+    if (optimized.relatedNotes.length < baseline.relatedNotes.length)
+        trimmedSections.push('related_notes');
+    return {
+        optimizedLists: optimized,
+        metadata: {
+            estimated_tokens_before: baselineTokens,
+            estimated_tokens_after: optimizedTokens,
+            budget_target: PROMPT_BUDGET_TARGET,
+            budget_max: PROMPT_BUDGET_MAX,
+            trimmed_sections: trimmedSections,
+        },
+    };
+}
+export function compilePromptMarkdown(input) {
+    const optimized = applyPromptBudget(input);
+    return {
+        markdown: renderPrompt(input, optimized.optimizedLists),
+        metadata: optimized.metadata,
+    };
+}
 export function saveCompiledPrompt(rootPath, runId, markdown) {
     const promptsPath = getSidecarPaths(rootPath).promptsPath;
     fs.mkdirSync(promptsPath, { recursive: true });

package/dist/prompts/prompt-service.js

@@ -11,18 +11,22 @@ export function compileTaskPrompt(input) {
         branch: task.tracking.branch,
         worktree: task.tracking.worktree,
     });
-    const promptMarkdown = compilePromptMarkdown({
+    const compiledPrompt = compilePromptMarkdown({
         task,
         run: created.run,
         runner: input.runner,
         agentRole: input.agentRole,
         linkedContext: input.linkedContext,
     });
-    const promptPath = saveCompiledPrompt(input.rootPath, created.run.run_id, promptMarkdown);
+    const promptPath = saveCompiledPrompt(input.rootPath, created.run.run_id, compiledPrompt.markdown);
     updateRunRecordEntry(input.rootPath, created.run.run_id, {
         status: 'queued',
         prompt_path: promptPath,
-        summary: `Compiled prompt for task ${task.task_id}`,
+        prompt_tokens_estimated_before: compiledPrompt.metadata.estimated_tokens_before,
+        prompt_tokens_estimated_after: compiledPrompt.metadata.estimated_tokens_after,
+        prompt_budget_target: compiledPrompt.metadata.budget_target,
+        prompt_trimmed_sections: compiledPrompt.metadata.trimmed_sections,
+        summary: `Compiled prompt for task ${task.task_id} (${compiledPrompt.metadata.estimated_tokens_before} -> ${compiledPrompt.metadata.estimated_tokens_after} est. tokens)`,
     });
     return {
         run_id: created.run.run_id,
@@ -30,6 +34,7 @@ export function compileTaskPrompt(input) {
         runner_type: input.runner,
         agent_role: input.agentRole,
         prompt_path: promptPath,
-        prompt_markdown: promptMarkdown,
+        prompt_markdown: compiledPrompt.markdown,
+        prompt_optimization: compiledPrompt.metadata,
     };
 }

package/dist/runs/run-record.js

@@ -28,6 +28,10 @@ export const runRecordSchema = z
     reviewed_at: z.string().datetime({ offset: true }).nullable().default(null),
     reviewed_by: z.string().default(''),
     review_note: z.string().default(''),
+    prompt_tokens_estimated_before: z.number().int().nonnegative().default(0),
+    prompt_tokens_estimated_after: z.number().int().nonnegative().default(0),
+    prompt_budget_target: z.number().int().nonnegative().default(0),
+    prompt_trimmed_sections: z.array(z.string()).default([]),
 })
     .strict();
 export const runRecordCreateInputSchema = runRecordSchema
@@ -49,6 +53,10 @@ export const runRecordCreateInputSchema = runRecordSchema
     reviewed_at: true,
     reviewed_by: true,
     review_note: true,
+    prompt_tokens_estimated_before: true,
+    prompt_tokens_estimated_after: true,
+    prompt_budget_target: true,
+    prompt_trimmed_sections: true,
 });
 export const runRecordUpdateInputSchema = z
     .object({
@@ -67,6 +75,10 @@ export const runRecordUpdateInputSchema = z
     reviewed_at: z.string().datetime({ offset: true }).nullable().optional(),
     reviewed_by: z.string().optional(),
     review_note: z.string().optional(),
+    prompt_tokens_estimated_before: z.number().int().nonnegative().optional(),
+    prompt_tokens_estimated_after: z.number().int().nonnegative().optional(),
+    prompt_budget_target: z.number().int().nonnegative().optional(),
+    prompt_trimmed_sections: z.array(z.string()).optional(),
 })
     .strict();
 export function createRunRecord(runId, input) {
@@ -92,6 +104,10 @@ export function createRunRecord(runId, input) {
         reviewed_at: input.reviewed_at ?? null,
         reviewed_by: input.reviewed_by ?? '',
         review_note: input.review_note ?? '',
+        prompt_tokens_estimated_before: input.prompt_tokens_estimated_before ?? 0,
+        prompt_tokens_estimated_after: input.prompt_tokens_estimated_after ?? 0,
+        prompt_budget_target: input.prompt_budget_target ?? 0,
+        prompt_trimmed_sections: input.prompt_trimmed_sections ?? [],
     };
     return runRecordSchema.parse(normalized);
 }

package/dist/runs/run-repository.js

@@ -53,6 +53,7 @@ export class RunRecordRepository {
             validation_results: parsedPatch.validation_results ?? existing.validation_results,
             blockers: parsedPatch.blockers ?? existing.blockers,
             follow_ups: parsedPatch.follow_ups ?? existing.follow_ups,
+            prompt_trimmed_sections: parsedPatch.prompt_trimmed_sections ?? existing.prompt_trimmed_sections,
         };
         const validated = runRecordSchema.parse(merged);
         const filePath = runFilePath(this.runsPath, runId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidecar-cli",
-  "version": "0.1.4",
+  "version": "0.1.5-beta.1",
   "description": "Local-first project memory and recording tool",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json",