@compilr-dev/sdk 0.7.23 → 0.7.25

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

@@ -7,6 +7,7 @@
  * - getTeamCheckpointer()/recordTeamActivity()/getCurrentProject() → artifacts.*
  */
 import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { truncateContent } from './truncate.js';
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function createArtifactTools(config) {
     // Safe: callers guard with `if (config.context.artifacts)` before calling
@@ -131,6 +132,8 @@ export function createArtifactTools(config) {
                     }
                     return createErrorResult(message);
                 }
+                // Auto-truncate large artifact content
+                const tc = truncateContent(artifact.content);
                 const output = [
                     `Artifact: ${artifact.name}`,
                     ``,
@@ -140,9 +143,12 @@ export function createArtifactTools(config) {
                     `Summary: ${artifact.summary}`,
                     `Created: ${artifact.createdAt.toISOString()}`,
                     `Updated: ${artifact.updatedAt.toISOString()}`,
+                    ...(tc.truncated
+                        ? [``, `[Content truncated: ${String(tc.originalChars)} chars total]`]
+                        : []),
                     ``,
                     `--- Content ---`,
-                    artifact.content,
+                    tc.content,
                 ].join('\n');
                 return createSuccessResult(output);
             }

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

@@ -8,6 +8,7 @@
  * Ported from CLI's src/tools/document-db.ts.
  */
 import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { truncateContent } from './truncate.js';
 /** All valid document types — keep in sync with DocumentType in types.ts. */
 const DOC_TYPE_ENUM = [
     // Software
@@ -253,15 +254,24 @@ export function createDocumentTools(config) {
                     content = allLines.slice(start, end).join('\n');
                     truncated = end < allLines.length;
                 }
+                // Auto-truncate large full reads to prevent context blowup
+                const tc = truncateContent(content);
+                if (tc.truncated)
+                    truncated = true;
                 return createSuccessResult({
                     success: true,
                     document: {
                         id: doc.id,
                         docType: doc.docType,
                         title: doc.title,
-                        content,
+                        content: tc.content,
                         totalLines,
-                        ...(truncated ? { truncated: true, hint: 'Use startLine/maxLines to read more' } : {}),
+                        ...(truncated
+                            ? {
+                                truncated: true,
+                                hint: 'Use summary_only, section, or startLine/maxLines for targeted reads',
+                            }
+                            : {}),
                         createdAt: doc.createdAt.toISOString(),
                         updatedAt: doc.updatedAt.toISOString(),
                     },

package/dist/platform/tools/plan-tools.d.ts

@@ -19,6 +19,7 @@ export declare function createPlanTools(config: PlatformToolsConfig): (import("@
 }> | import("@compilr-dev/agents").Tool<{
     plan_id?: number;
     name?: string;
+    summary_only?: boolean;
     project_id?: number;
 }> | import("@compilr-dev/agents").Tool<{
     project_id?: number;

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

@@ -6,6 +6,7 @@
  * Ported from CLI's src/tools/plan-tools.ts.
  */
 import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { truncateContent } from './truncate.js';
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function createPlanTools(config) {
     const { context: ctx } = config;
@@ -140,7 +141,7 @@ export function createPlanTools(config) {
     // ---------------------------------------------------------------------------
     const planGetTool = defineTool({
         name: 'plan_get',
-        description: 'Get a plan by ID or name. Returns the full plan content and linked work item details.',
+        description: 'Get a plan by ID or name. Returns plan content and linked work item. Large plans are auto-truncated.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -152,6 +153,10 @@ export function createPlanTools(config) {
                     type: 'string',
                     description: 'Plan name (alternative to ID)',
                 },
+                summary_only: {
+                    type: 'boolean',
+                    description: 'If true, returns plan metadata and headings without full content.',
+                },
                 project_id: {
                     type: 'number',
                     description: 'Override active project (required for name lookup).',
@@ -185,13 +190,44 @@ export function createPlanTools(config) {
                         message: 'Plan not found',
                     });
                 }
+                // summary_only: return metadata + headings without full content
+                if (input.summary_only) {
+                    const lines = plan.content.split('\n');
+                    const headings = lines
+                        .map((l, i) => ({ line: i + 1, heading: l.trim() }))
+                        .filter((h) => h.heading.match(/^#{1,6}\s/));
+                    return createSuccessResult({
+                        success: true,
+                        plan: {
+                            id: plan.id,
+                            name: plan.name,
+                            status: plan.status,
+                            totalChars: plan.content.length,
+                            headings,
+                            workItemId: plan.workItemId,
+                            workItem: plan.workItem
+                                ? {
+                                    id: plan.workItem.id,
+                                    itemId: plan.workItem.itemId,
+                                    title: plan.workItem.title,
+                                    status: plan.workItem.status,
+                                }
+                                : null,
+                            createdAt: plan.createdAt.toISOString(),
+                            updatedAt: plan.updatedAt.toISOString(),
+                        },
+                    });
+                }
+                // Auto-truncate large plans
+                const tc = truncateContent(plan.content);
                 return createSuccessResult({
                     success: true,
                     plan: {
                         id: plan.id,
                         name: plan.name,
-                        content: plan.content,
+                        content: tc.content,
                         status: plan.status,
+                        ...(tc.truncated ? { truncated: true, originalChars: tc.originalChars } : {}),
                         workItemId: plan.workItemId,
                         workItem: plan.workItem
                             ? {

package/dist/platform/tools/truncate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared output truncation for platform tools.
+ *
+ * Uses head-and-tail strategy (70% head / 20% tail) matching
+ * the pattern used by read_file and bash in the agents library.
+ */
+/** Default max content size for tool output (~25K chars ≈ 6K tokens) */
+export declare const DEFAULT_MAX_CONTENT_CHARS = 25000;
+/**
+ * Truncate content using head-and-tail strategy.
+ * Returns the original content if under the limit.
+ */
+export declare function truncateContent(content: string, maxChars?: number): {
+    content: string;
+    truncated: boolean;
+    originalChars: number;
+};

package/dist/platform/tools/truncate.js

@@ -0,0 +1,27 @@
+/**
+ * Shared output truncation for platform tools.
+ *
+ * Uses head-and-tail strategy (70% head / 20% tail) matching
+ * the pattern used by read_file and bash in the agents library.
+ */
+/** Default max content size for tool output (~25K chars ≈ 6K tokens) */
+export const DEFAULT_MAX_CONTENT_CHARS = 25_000;
+/**
+ * Truncate content using head-and-tail strategy.
+ * Returns the original content if under the limit.
+ */
+export function truncateContent(content, maxChars = DEFAULT_MAX_CONTENT_CHARS) {
+    if (content.length <= maxChars) {
+        return { content, truncated: false, originalChars: content.length };
+    }
+    const headSize = Math.floor(maxChars * 0.7);
+    const tailSize = Math.floor(maxChars * 0.2);
+    const omitted = content.length - headSize - tailSize;
+    const head = content.slice(0, headSize);
+    const tail = content.slice(-tailSize);
+    return {
+        content: `${head}\n\n... [${String(omitted)} chars truncated — use startLine/maxLines or section for targeted reads] ...\n\n${tail}`,
+        truncated: true,
+        originalChars: content.length,
+    };
+}

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

@@ -102,15 +102,21 @@ export function createWorkItemTools(config) {
                         commitHash: item.commitHash,
                         createdAt: item.createdAt.toISOString(),
                     };
-                    // Always include full comments for single-item lookup
+                    // Include recent comments for single-item lookup (max 10)
                     if (comments) {
                         const itemComments = await comments.listByWorkItem(item.id);
-                        itemData.comments = itemComments.map((c) => ({
+                        const MAX_COMMENTS = 10;
+                        const limited = itemComments.slice(-MAX_COMMENTS);
+                        itemData.comments = limited.map((c) => ({
                             id: c.id,
                             author: c.author,
-                            content: c.content,
+                            content: c.content.length > 2000 ? c.content.slice(0, 2000) + '... [truncated]' : c.content,
                             createdAt: c.createdAt.toISOString(),
                         }));
+                        if (itemComments.length > MAX_COMMENTS) {
+                            itemData.totalComments = itemComments.length;
+                            itemData.commentsShown = MAX_COMMENTS;
+                        }
                     }
                     return createSuccessResult({
                         success: true,
@@ -157,12 +163,19 @@ export function createWorkItemTools(config) {
                         return base;
                     if (wantFullComments) {
                         const itemComments = await comments.listByWorkItem(item.id);
-                        base.comments = itemComments.map((c) => ({
+                        const MAX_COMMENTS_PER_ITEM = 5;
+                        const limited = itemComments.slice(-MAX_COMMENTS_PER_ITEM);
+                        base.comments = limited.map((c) => ({
                             id: c.id,
                             author: c.author,
-                            content: c.content,
+                            content: c.content.length > 2000
+                                ? c.content.slice(0, 2000) + '... [truncated]'
+                                : c.content,
                             createdAt: c.createdAt.toISOString(),
                         }));
+                        if (itemComments.length > MAX_COMMENTS_PER_ITEM) {
+                            base.totalComments = itemComments.length;
+                        }
                     }
                     else {
                         base.commentCount = await comments.countByWorkItem(item.id);

package/dist/system-prompt/modules.js

@@ -243,21 +243,31 @@ Project documents (drafts, outlines, analyses, plans) are stored in the **databa
 export const DELEGATION_MODULE = {
     id: 'delegation',
     name: 'Token Efficiency & Delegation',
-    estimatedTokens: 200,
-    content: `## Token Efficiency & Delegation
-
-Use the **task** tool (sub-agent) for:
-- **File exploration**: "find files", "what's in this directory", "explore codebase"
-- **Code search**: "where is X defined", "find usages of Y"
-- **Analysis**: "analyze module", "understand architecture", "review code"
-- **Multi-file operations**: Tasks touching 5+ files
-
-### Rules
-1. Exploration/search questions → task(explore)
-2. Code review → task(code-review)
-3. Planning → task(plan)
-4. Simple answers (no file access) → respond directly
-5. Code edits → do it yourself (never delegate edits)`,
+    estimatedTokens: 350,
+    content: `## CRITICAL: Subagent Delegation
+
+The **task** tool spawns a subagent that works in isolated context and returns a summary. This is your primary tool for exploration, search, and analysis.
+
+**Why this matters:** Reading 5 files directly costs ~25,000 tokens in YOUR context. Delegating to a subagent costs ~200 tokens (tool call + summary). The subagent sees the full content but only the summary enters your history. This 100x reduction keeps your context clean for the actual work.
+
+### ALWAYS delegate these:
+- **File exploration**: "find files", "what's in this directory", "explore the codebase" → \`task(explore)\`
+- **Code search**: "where is X defined", "find usages of Y", "how does Z work" → \`task(explore)\`
+- **Analysis**: "analyze this module", "understand the architecture", "review this code" → \`task(code-review)\`
+- **Multi-file reads**: Any task requiring 3+ file reads → \`task(explore)\`
+- **Research**: web searches, documentation lookups → \`task(explore)\`
+
+### NEVER delegate these:
+- **Code edits**: Writing/editing files — do it yourself
+- **Simple answers**: Questions you can answer from memory
+- **User interaction**: Asking the user questions
+- **Single file reads**: Reading 1-2 specific files the user pointed to
+
+### Examples
+- User: "What files implement the auth system?" → \`task({ type: "explore", message: "Find all files related to authentication..." })\`
+- User: "How does the payment module work?" → \`task({ type: "explore", message: "Analyze the payment module..." })\`
+- User: "Fix the bug in login.tsx" → Read login.tsx yourself, then edit it
+- User: "Add a logout button" → Read the relevant file yourself, then edit it`,
 };
 /**
  * Git safety module - only if hasGit=true
@@ -326,9 +336,9 @@ export const IMPORTANT_RULES_MODULE = {
 4. Use todo_write for multi-step tasks (3+ steps)
 5. Don't over-engineer - implement exactly what was asked
 6. Check for security issues - fix insecure code immediately
-7. **DELEGATE exploration to sub-agents** - use task(explore) for file searches, code navigation, and analysis. NEVER accumulate exploration results in your own context.
-8. Call suggest tool after completing tasks (don't write "suggest:" as text)
-9. When user asks "what files...", "where is...", "find..." - ALWAYS use task(explore), not direct tool calls`,
+7. **DELEGATE exploration to sub-agents** - use task(explore) for searches, analysis, and multi-file reads. Each file you read directly costs thousands of tokens in YOUR context. A subagent reads files in isolation and returns a compact summary.
+8. When user asks "what files...", "where is...", "find...", "how does X work..." → ALWAYS use task(explore), never read files directly to answer
+9. Call suggest tool after completing tasks (don't write "suggest:" as text)`,
 };
 /**
  * Environment module - always included

package/dist/team/tool-config.js

@@ -431,6 +431,7 @@ export const TOOL_PROFILES = {
         'interaction',
         'handoff',
         'guide',
+        'subagents',
         'meta',
         'git_read',
         'project',
@@ -444,6 +445,7 @@ export const TOOL_PROFILES = {
         'interaction',
         'handoff',
         'guide',
+        'subagents',
         'meta',
         'project',
         'search',
@@ -460,6 +462,7 @@ export const TOOL_PROFILES = {
         'interaction',
         'handoff',
         'guide',
+        'subagents',
         'meta',
         'git_read',
         'git_write',
@@ -476,6 +479,7 @@ export const TOOL_PROFILES = {
         'interaction',
         'handoff',
         'guide',
+        'subagents',
         'meta',
         'git_read',
         'project',
@@ -490,6 +494,7 @@ export const TOOL_PROFILES = {
         'interaction',
         'handoff',
         'guide',
+        'subagents',
         'meta',
         'git_read',
         'project',
@@ -511,6 +516,7 @@ export const TOOL_PROFILES = {
         'interaction',
         'handoff',
         'guide',
+        'subagents',
         'meta',
         'git_read',
         'project',
@@ -532,6 +538,7 @@ export const TOOL_PROFILES = {
         'interaction',
         'handoff',
         'guide',
+        'subagents',
         'meta',
         'project',
         'backlog_read',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.7.23",
+  "version": "0.7.25",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",