@compilr-dev/agents 0.3.7 → 0.3.9

package/dist/providers/fireworks.d.ts

@@ -57,6 +57,14 @@ export declare class FireworksProvider extends OpenAICompatibleProvider {
      * Fireworks AI uses standard OpenAI body format
      */
     protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Extract cache statistics from Fireworks response headers.
+     * Fireworks returns cache stats in headers rather than the JSON body.
+     * @see https://docs.fireworks.ai/guides/prompt-caching
+     */
+    protected extractCacheStatsFromHeaders(headers: Headers): {
+        cacheReadTokens?: number;
+    };
     /**
      * Map HTTP errors with Fireworks AI-specific messages
      */

package/dist/providers/fireworks.js

@@ -65,6 +65,21 @@ export class FireworksProvider extends OpenAICompatibleProvider {
     buildProviderSpecificBody(_options) {
         return {};
     }
+    /**
+     * Extract cache statistics from Fireworks response headers.
+     * Fireworks returns cache stats in headers rather than the JSON body.
+     * @see https://docs.fireworks.ai/guides/prompt-caching
+     */
+    extractCacheStatsFromHeaders(headers) {
+        const cachedTokens = headers.get('fireworks-cached-prompt-tokens');
+        if (cachedTokens) {
+            const parsed = parseInt(cachedTokens, 10);
+            if (!isNaN(parsed) && parsed > 0) {
+                return { cacheReadTokens: parsed };
+            }
+        }
+        return {};
+    }
     /**
      * Map HTTP errors with Fireworks AI-specific messages
      */

package/dist/providers/openai-compatible.d.ts

@@ -149,6 +149,15 @@ export declare abstract class OpenAICompatibleProvider implements LLMProvider {
      * @returns ProviderError with appropriate message
      */
     protected abstract mapConnectionError(error: Error): ProviderError;
+    /**
+     * Extract cache statistics from response headers.
+     * Override in subclasses for providers that return cache stats in headers (e.g., Fireworks).
+     * @param headers Response headers
+     * @returns Partial LLMUsage with cache stats
+     */
+    protected extractCacheStatsFromHeaders(_headers: Headers): {
+        cacheReadTokens?: number;
+    };
     /**
      * Stream chat completion from the provider
      *

package/dist/providers/openai-compatible.js

@@ -42,6 +42,15 @@ export class OpenAICompatibleProvider {
         this.defaultMaxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
         this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
     }
+    /**
+     * Extract cache statistics from response headers.
+     * Override in subclasses for providers that return cache stats in headers (e.g., Fireworks).
+     * @param headers Response headers
+     * @returns Partial LLMUsage with cache stats
+     */
+    extractCacheStatsFromHeaders(_headers) {
+        return {};
+    }
     // ==================== SHARED IMPLEMENTATION ====================
     /**
      * Stream chat completion from the provider
@@ -106,6 +115,8 @@ export class OpenAICompatibleProvider {
                 const errorBody = await response.text();
                 throw this.mapHttpError(response.status, errorBody, model);
             }
+            // Extract cache stats from headers (for providers like Fireworks)
+            const headerCacheStats = this.extractCacheStatsFromHeaders(response.headers);
             const reader = response.body?.getReader();
             if (!reader) {
                 throw new ProviderError('No response body', this.name);
@@ -153,12 +164,12 @@ export class OpenAICompatibleProvider {
                     }
                 }
             }
-            // Yield done chunk with usage
+            // Yield done chunk with usage (merge header-based cache stats)
             yield {
                 type: 'done',
                 usage: usage
-                    ? { ...usage, debugPayload }
-                    : { inputTokens: 0, outputTokens: 0, debugPayload },
+                    ? { ...usage, ...headerCacheStats, debugPayload }
+                    : { inputTokens: 0, outputTokens: 0, ...headerCacheStats, debugPayload },
             };
         }
         catch (error) {

package/dist/tools/builtin/index.d.ts

@@ -22,7 +22,7 @@ export type { GlobInput } from './glob.js';
 export { editTool, createEditTool } from './edit.js';
 export type { EditInput } from './edit.js';
 export { todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, } from './todo.js';
-export type { TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, } from './todo.js';
+export type { TodoWriteInput, TodoReadInput, TodoClaimInput, TodoHandoffInput, TodoItem, TodoStatus, TodoContextCleanupOptions, } from './todo.js';
 export { createTaskTool, defaultAgentTypes } from './task.js';
 export type { TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, } from './task.js';
 export { webFetchTool, createWebFetchTool } from './web-fetch.js';

package/dist/tools/builtin/todo.d.ts

@@ -33,6 +33,11 @@ export interface TodoItem {
      * Optional priority (higher = more important)
      */
     priority?: number;
+    /**
+     * Owner agent ID (e.g., 'pm', 'arch', 'dev')
+     * If undefined/null, the task is unassigned
+     */
+    owner?: string;
     /**
      * Creation timestamp
      */
@@ -54,6 +59,7 @@ export interface TodoWriteInput {
         status: TodoStatus;
         activeForm?: string;
         priority?: number;
+        owner?: string;
     }>;
 }
 /**
@@ -68,6 +74,13 @@ export interface TodoReadInput {
      * Include completed tasks (default: true)
      */
     includeCompleted?: boolean;
+    /**
+     * Filter by owner (optional)
+     * - Specific agent ID: Return only tasks owned by that agent
+     * - 'unassigned': Return only tasks without an owner
+     * - undefined: Return all tasks (no filter)
+     */
+    owner?: string;
 }
 /**
  * TodoStore manages the in-memory task list
@@ -83,6 +96,11 @@ export declare class TodoStore {
      * Get todos filtered by status
      */
     getByStatus(status: TodoStatus): TodoItem[];
+    /**
+     * Get todos filtered by owner
+     * @param owner - Agent ID, or 'unassigned' for tasks without owner
+     */
+    getByOwner(owner: string): TodoItem[];
     /**
      * Replace all todos with a new list
      */
@@ -91,6 +109,7 @@ export declare class TodoStore {
         status: TodoStatus;
         activeForm?: string;
         priority?: number;
+        owner?: string;
     }>): void;
     /**
      * Add a single todo
@@ -100,6 +119,7 @@ export declare class TodoStore {
         status: TodoStatus;
         activeForm?: string;
         priority?: number;
+        owner?: string;
     }): TodoItem;
     /**
      * Update a todo by ID
@@ -117,6 +137,12 @@ export declare class TodoStore {
      * Get count by status
      */
     getCounts(): Record<TodoStatus, number>;
+    /**
+     * Get counts by owner
+     * Returns a map of owner ID to count
+     * 'unassigned' key contains count of todos without owner
+     */
+    getCountsByOwner(): Record<string, number>;
 }
 /**
  * TodoWrite tool - Update the task list
@@ -126,12 +152,44 @@ export declare const todoWriteTool: Tool<TodoWriteInput>;
  * TodoRead tool - Get the current task list
  */
 export declare const todoReadTool: Tool<TodoReadInput>;
+/**
+ * Input for TodoClaim tool
+ */
+export interface TodoClaimInput {
+    /**
+     * The todo ID to claim
+     */
+    todoId: string;
+    /**
+     * The agent ID claiming the todo
+     */
+    agentId: string;
+}
+/**
+ * Input for TodoHandoff tool
+ */
+export interface TodoHandoffInput {
+    /**
+     * The todo ID to hand off
+     */
+    todoId: string;
+    /**
+     * The agent ID to hand off to
+     */
+    toAgentId: string;
+    /**
+     * Optional notes about the handoff
+     */
+    notes?: string;
+}
 /**
  * Factory to create todo tools with a custom store
  */
 export declare function createTodoTools(store?: TodoStore): {
     todoWrite: Tool<TodoWriteInput>;
     todoRead: Tool<TodoReadInput>;
+    todoClaim: Tool<TodoClaimInput>;
+    todoHandoff: Tool<TodoHandoffInput>;
     store: TodoStore;
 };
 /**

package/dist/tools/builtin/todo.js

@@ -39,6 +39,16 @@ export class TodoStore {
     getByStatus(status) {
         return this.getAll().filter((t) => t.status === status);
     }
+    /**
+     * Get todos filtered by owner
+     * @param owner - Agent ID, or 'unassigned' for tasks without owner
+     */
+    getByOwner(owner) {
+        if (owner === 'unassigned') {
+            return this.getAll().filter((t) => !t.owner);
+        }
+        return this.getAll().filter((t) => t.owner === owner);
+    }
     /**
      * Replace all todos with a new list
      */
@@ -53,6 +63,7 @@ export class TodoStore {
                 status: todo.status,
                 activeForm: todo.activeForm,
                 priority: todo.priority,
+                owner: todo.owner,
                 createdAt: now,
                 updatedAt: now,
             });
@@ -70,6 +81,7 @@ export class TodoStore {
             status: todo.status,
             activeForm: todo.activeForm,
             priority: todo.priority,
+            owner: todo.owner,
             createdAt: now,
             updatedAt: now,
         };
@@ -117,6 +129,23 @@ export class TodoStore {
         }
         return counts;
     }
+    /**
+     * Get counts by owner
+     * Returns a map of owner ID to count
+     * 'unassigned' key contains count of todos without owner
+     */
+    getCountsByOwner() {
+        const counts = { unassigned: 0 };
+        for (const todo of this.todos.values()) {
+            if (todo.owner) {
+                counts[todo.owner] = (counts[todo.owner] ?? 0) + 1;
+            }
+            else {
+                counts['unassigned']++;
+            }
+        }
+        return counts;
+    }
 }
 /**
  * Global default store (can be overridden with factory functions)
@@ -127,8 +156,9 @@ const defaultStore = new TodoStore();
  */
 export const todoWriteTool = defineTool({
     name: 'todo_write',
-    description: 'Update the task list. Provide the complete list of todos. ' +
-        'Use this to track progress on multi-step tasks.',
+    description: 'Update the SESSION todo list (shown in CLI footer). These are ephemeral tasks for the current session only - ' +
+        'NOT persistent backlog items. For persistent project backlog, use workitem_* tools. ' +
+        'Provide the complete list to replace current todos.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -155,6 +185,10 @@ export const todoWriteTool = defineTool({
                             type: 'number',
                             description: 'Priority (higher = more important)',
                         },
+                        owner: {
+                            type: 'string',
+                            description: 'Owner agent ID (e.g., "dev", "pm", "arch"). Omit for unassigned tasks.',
+                        },
                     },
                     required: ['content', 'status'],
                 },
@@ -186,7 +220,8 @@ export const todoWriteTool = defineTool({
  */
 export const todoReadTool = defineTool({
     name: 'todo_read',
-    description: 'Get the current task list. Optionally filter by status.',
+    description: 'Get the SESSION todo list (shown in CLI footer). These are ephemeral session tasks - ' +
+        'for persistent project backlog, use workitem_query. Optionally filter by status or owner.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -199,6 +234,10 @@ export const todoReadTool = defineTool({
                 type: 'boolean',
                 description: 'Include completed tasks (default: true)',
             },
+            owner: {
+                type: 'string',
+                description: 'Filter by owner agent ID, or "unassigned" for tasks without owner (optional)',
+            },
         },
     },
     execute: (input) => {
@@ -211,6 +250,15 @@ export const todoReadTool = defineTool({
         if (input.includeCompleted === false) {
             todos = todos.filter((t) => t.status !== 'completed');
         }
+        // Filter by owner if specified
+        if (input.owner) {
+            if (input.owner === 'unassigned') {
+                todos = todos.filter((t) => !t.owner);
+            }
+            else {
+                todos = todos.filter((t) => t.owner === input.owner);
+            }
+        }
         const counts = defaultStore.getCounts();
         return Promise.resolve(createSuccessResult({
             todos: todos.map((t) => ({
@@ -219,6 +267,7 @@ export const todoReadTool = defineTool({
                 status: t.status,
                 activeForm: t.activeForm,
                 priority: t.priority,
+                owner: t.owner,
             })),
             counts,
             total: todos.length,
@@ -232,8 +281,8 @@ export function createTodoTools(store) {
     const todoStore = store ?? new TodoStore();
     const todoWrite = defineTool({
         name: 'todo_write',
-        description: 'Update the task list. Provide the complete list of todos. ' +
-            'Use this to track progress on multi-step tasks.',
+        description: 'Update the SESSION todo list (shown in CLI footer). These are ephemeral tasks for the current session only - ' +
+            'NOT persistent backlog items. For persistent project backlog, use workitem_* tools.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -247,6 +296,7 @@ export function createTodoTools(store) {
                             status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
                             activeForm: { type: 'string' },
                             priority: { type: 'number' },
+                            owner: { type: 'string' },
                         },
                         required: ['content', 'status'],
                     },
@@ -275,7 +325,8 @@ export function createTodoTools(store) {
     });
     const todoRead = defineTool({
         name: 'todo_read',
-        description: 'Get the current task list. Optionally filter by status.',
+        description: 'Get the SESSION todo list (shown in CLI footer). These are ephemeral session tasks - ' +
+            'for persistent project backlog, use workitem_query.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -286,6 +337,10 @@ export function createTodoTools(store) {
                 includeCompleted: {
                     type: 'boolean',
                 },
+                owner: {
+                    type: 'string',
+                    description: 'Filter by owner agent ID, or "unassigned" for tasks without owner',
+                },
             },
         },
         execute: (input) => {
@@ -296,6 +351,14 @@ export function createTodoTools(store) {
             if (input.includeCompleted === false) {
                 todos = todos.filter((t) => t.status !== 'completed');
             }
+            if (input.owner) {
+                if (input.owner === 'unassigned') {
+                    todos = todos.filter((t) => !t.owner);
+                }
+                else {
+                    todos = todos.filter((t) => t.owner === input.owner);
+                }
+            }
             const counts = todoStore.getCounts();
             return Promise.resolve(createSuccessResult({
                 todos: todos.map((t) => ({
@@ -304,6 +367,7 @@ export function createTodoTools(store) {
                     status: t.status,
                     activeForm: t.activeForm,
                     priority: t.priority,
+                    owner: t.owner,
                 })),
                 counts,
                 total: todos.length,
@@ -311,7 +375,94 @@ export function createTodoTools(store) {
         },
         silent: true,
     });
-    return { todoWrite, todoRead, store: todoStore };
+    const todoClaim = defineTool({
+        name: 'todo_claim',
+        description: 'Claim an unassigned SESSION todo (from CLI footer). For persistent backlog items, use workitem_claim.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                todoId: {
+                    type: 'string',
+                    description: 'The todo ID to claim',
+                },
+                agentId: {
+                    type: 'string',
+                    description: 'The agent ID claiming the todo',
+                },
+            },
+            required: ['todoId', 'agentId'],
+        },
+        execute: (input) => {
+            const todos = todoStore.getAll();
+            const todo = todos.find((t) => t.id === input.todoId);
+            if (!todo) {
+                return Promise.resolve(createErrorResult(`Todo "${input.todoId}" not found`));
+            }
+            if (todo.owner) {
+                return Promise.resolve(createErrorResult(`Todo "${input.todoId}" is already owned by "${todo.owner}"`));
+            }
+            const updated = todoStore.update(input.todoId, { owner: input.agentId });
+            if (!updated) {
+                return Promise.resolve(createErrorResult(`Failed to update todo "${input.todoId}"`));
+            }
+            return Promise.resolve(createSuccessResult({
+                message: `Todo "${input.todoId}" claimed by "${input.agentId}"`,
+                todo: {
+                    id: updated.id,
+                    content: updated.content,
+                    status: updated.status,
+                    owner: updated.owner,
+                },
+            }));
+        },
+    });
+    const todoHandoff = defineTool({
+        name: 'todo_handoff',
+        description: 'Hand off a SESSION todo (from CLI footer) to another agent. ' +
+            'For persistent backlog items, use workitem_handoff.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                todoId: {
+                    type: 'string',
+                    description: 'The todo ID to hand off',
+                },
+                toAgentId: {
+                    type: 'string',
+                    description: 'The agent ID to hand off to',
+                },
+                notes: {
+                    type: 'string',
+                    description: 'Optional notes about the handoff (context, status, blockers)',
+                },
+            },
+            required: ['todoId', 'toAgentId'],
+        },
+        execute: (input) => {
+            const todos = todoStore.getAll();
+            const todo = todos.find((t) => t.id === input.todoId);
+            if (!todo) {
+                return Promise.resolve(createErrorResult(`Todo "${input.todoId}" not found`));
+            }
+            const previousOwner = todo.owner;
+            const updated = todoStore.update(input.todoId, { owner: input.toAgentId });
+            if (!updated) {
+                return Promise.resolve(createErrorResult(`Failed to update todo "${input.todoId}"`));
+            }
+            return Promise.resolve(createSuccessResult({
+                message: `Todo "${input.todoId}" handed off from "${previousOwner ?? 'unassigned'}" to "${input.toAgentId}"`,
+                todo: {
+                    id: updated.id,
+                    content: updated.content,
+                    status: updated.status,
+                    owner: updated.owner,
+                },
+                previousOwner,
+                notes: input.notes,
+            }));
+        },
+    });
+    return { todoWrite, todoRead, todoClaim, todoHandoff, store: todoStore };
 }
 /**
  * Reset the default store (useful for testing)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",