@teammates/cli 0.2.7 → 0.3.0

package/README.md

@@ -128,12 +128,14 @@ The CLI uses a generic adapter interface to support any coding agent. Each adapt
 
 ### How Adapters Work
 
-1. The orchestrator builds a full prompt (identity + memory + roster + task)
-2. The prompt is written to a temp file
-3. The agent CLI is spawned with the prompt
-4. stdout/stderr are captured for result parsing
-5. The output is parsed for embedded handoff blocks
-6. Temp files are cleaned up
+1. The adapter queries the recall index for relevant memories (automatic, in-process)
+2. The orchestrator builds a full prompt (SOUL → WISDOM → recall results → daily logs → weekly summaries → session history → roster → task)
+3. The prompt is written to a temp file
+4. The agent CLI is spawned with the prompt
+5. stdout/stderr are captured for result parsing
+6. The output is parsed for embedded handoff blocks
+7. The recall index is synced to pick up any files the agent created/modified
+8. Temp files are cleaned up
 
 ### Writing a Custom Adapter
 
@@ -214,6 +216,10 @@ Tests use [Vitest](https://vitest.dev/) and cover the core modules:
 | `src/registry.test.ts` | Teammate discovery, SOUL.md parsing (role, ownership), daily logs |
 | `src/adapters/echo.test.ts` | Echo adapter session and task execution |
 
+## Dependencies
+
+- **`@teammates/recall`** — Bundled as a direct dependency. Provides automatic semantic search over teammate memories before every task. No separate installation or configuration needed.
+
 ## Requirements
 
 - Node.js >= 20

package/dist/adapter.d.ts

@@ -5,6 +5,7 @@
  * Each adapter wraps a specific agent backend (Codex, Claude Code, Cursor, etc.)
  * and translates between the orchestrator's protocol and the agent's native API.
  */
+import { type SearchResult } from "@teammates/recall";
 import type { TaskResult, TeammateConfig } from "./types.js";
 export interface AgentAdapter {
     /** Human-readable name of the agent backend (e.g. "codex", "claude-code") */
@@ -49,6 +50,23 @@ export interface InstalledService {
     description: string;
     usage: string;
 }
+/** Recall search results formatted for prompt injection. */
+export interface RecallContext {
+    results: SearchResult[];
+    /** Whether the query succeeded (false = index missing or search errored) */
+    ok: boolean;
+}
+/**
+ * Query the recall index for context relevant to the task prompt.
+ * Returns search results that should be injected into the teammate prompt.
+ * Skips auto-sync (sync happens after tasks, not before — keeps pre-task fast).
+ */
+export declare function queryRecallContext(teammatesDir: string, teammateName: string, taskPrompt: string): Promise<RecallContext>;
+/**
+ * Sync the recall index for a teammate (or all teammates).
+ * Wrapper around the recall library's Indexer.
+ */
+export declare function syncRecallIndex(teammatesDir: string, teammate?: string): Promise<void>;
 /**
  * Build the full prompt for a teammate session.
  * Includes identity, memory, roster, output protocol, and the task.
@@ -58,6 +76,8 @@ export declare function buildTeammatePrompt(teammate: TeammateConfig, taskPrompt
     roster?: RosterEntry[];
     services?: InstalledService[];
     sessionFile?: string;
+    sessionContent?: string;
+    recallResults?: SearchResult[];
 }): string;
 /**
  * Format a handoff envelope into a human-readable context string.

package/dist/adapter.js

@@ -5,6 +5,41 @@
  * Each adapter wraps a specific agent backend (Codex, Claude Code, Cursor, etc.)
  * and translates between the orchestrator's protocol and the agent's native API.
  */
+import { Indexer, search } from "@teammates/recall";
+/**
+ * Query the recall index for context relevant to the task prompt.
+ * Returns search results that should be injected into the teammate prompt.
+ * Skips auto-sync (sync happens after tasks, not before — keeps pre-task fast).
+ */
+export async function queryRecallContext(teammatesDir, teammateName, taskPrompt) {
+    try {
+        const results = await search(taskPrompt, {
+            teammatesDir,
+            teammate: teammateName,
+            maxResults: 5,
+            maxChunks: 3,
+            maxTokens: 500,
+            skipSync: true,
+        });
+        return { results, ok: true };
+    }
+    catch {
+        return { results: [], ok: false };
+    }
+}
+/**
+ * Sync the recall index for a teammate (or all teammates).
+ * Wrapper around the recall library's Indexer.
+ */
+export async function syncRecallIndex(teammatesDir, teammate) {
+    const indexer = new Indexer({ teammatesDir });
+    if (teammate) {
+        await indexer.syncTeammate(teammate);
+    }
+    else {
+        await indexer.syncAll();
+    }
+}
 /**
  * Build the full prompt for a teammate session.
  * Includes identity, memory, roster, output protocol, and the task.
@@ -21,6 +56,19 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
         parts.push(teammate.wisdom);
         parts.push("\n---\n");
     }
+    // ── Recall results (relevant episodic & semantic memories) ────────
+    if (options?.recallResults && options.recallResults.length > 0) {
+        parts.push("## Relevant Memories (from recall search)\n");
+        parts.push("These memories were retrieved based on relevance to the current task:\n");
+        for (const r of options.recallResults) {
+            const label = r.contentType
+                ? `[${r.contentType}] ${r.uri}`
+                : r.uri;
+            parts.push(`### ${label}\n${r.text}\n`);
+        }
+        parts.push("\n---\n");
+    }
+    // ── Recent daily logs ──────────────────────────────────────────────
     if (teammate.dailyLogs.length > 0) {
         parts.push("## Recent Daily Logs\n");
         for (const log of teammate.dailyLogs.slice(0, 7)) {
@@ -36,6 +84,13 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
         }
         parts.push("\n---\n");
     }
+    // ── Session history (prior tasks in this session) ─────────────────
+    if (options?.sessionContent?.trim()) {
+        parts.push("## Session History\n");
+        parts.push("These are entries from your prior tasks in this session:\n");
+        parts.push(options.sessionContent);
+        parts.push("\n---\n");
+    }
     // ── Team roster ───────────────────────────────────────────────────
     if (options?.roster && options.roster.length > 0) {
         parts.push("## Your Team\n");
@@ -72,8 +127,6 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
         parts.push("## Session State\n");
         parts.push(`Your session file is at: \`${options.sessionFile}\`
 
-**Read this file first** — it contains context from your prior tasks in this session.
-
 **Before returning your result**, append a brief entry to this file with:
 - What you did
 - Key decisions made
@@ -103,8 +156,10 @@ These files are your persistent memory. Without them, your next session starts f
 `);
     parts.push("\n---\n");
     // ── Output protocol ───────────────────────────────────────────────
-    parts.push("## Output Protocol\n");
-    parts.push(`Your response is a message. Format it as:
+    parts.push("## Output Protocol (CRITICAL)\n");
+    parts.push(`**Your #1 job is to produce a visible text response.** Session updates and memory writes are secondary — they support continuity but are not the deliverable. The user sees ONLY your text output. If you update files but return no text, the user sees an empty message and your work is invisible.
+
+Format your response as:
 
 \`\`\`
 TO: user
@@ -123,9 +178,9 @@ TO: user
 \`\`\`
 
 **Rules:**
+- **You MUST end your turn with visible text output.** A turn that ends with only tool calls and no text is a failed turn.
 - The \`# Subject\` line is REQUIRED — it becomes the message title.
 - Always write a substantive body. Never return just the subject.
-- **Your final message MUST contain your response text.** Do not end your turn with only tool calls — always finish with a visible message to the user.
 - Use markdown: headings, lists, code blocks, bold, etc.
 - Do as much work as you can before handing off.
 - Only hand off to teammates listed in "Your Team" above.
@@ -140,6 +195,9 @@ TO: user
     // ── Task ──────────────────────────────────────────────────────────
     parts.push("## Task\n");
     parts.push(taskPrompt);
+    parts.push("\n---\n");
+    // ── Final reminder (last thing the agent reads) ─────────────────
+    parts.push("**REMINDER: After completing the task and updating session/memory files, you MUST produce a text response starting with `TO: user`. An empty response is a bug.**");
     return parts.join("\n");
 }
 /**

package/dist/adapters/cli-proxy.d.ts

@@ -16,15 +16,33 @@
  */
 import type { AgentAdapter, InstalledService, RosterEntry } from "../adapter.js";
 import type { SandboxLevel, TaskResult, TeammateConfig } from "../types.js";
+/** Structured result from spawning an agent subprocess. */
+export interface SpawnResult {
+    /** Combined stdout + stderr (for backward compat / display) */
+    output: string;
+    /** stdout only */
+    stdout: string;
+    /** stderr only */
+    stderr: string;
+    /** Process exit code (null if killed by signal) */
+    exitCode: number | null;
+    /** Signal that killed the process (null if exited normally) */
+    signal: string | null;
+    /** Whether the process was killed by our timeout */
+    timedOut: boolean;
+    /** Path to the debug log file, if one was written */
+    debugFile?: string;
+}
 export interface AgentPreset {
     /** Display name */
     name: string;
     /** Binary / command to spawn */
     command: string;
-    /** Build CLI args. `promptFile` is a temp file path, `prompt` is the raw text. */
+    /** Build CLI args. `promptFile` is a temp file path, `prompt` is the raw text, `debugFile` is an optional path for agent debug logs. */
     buildArgs(ctx: {
         promptFile: string;
         prompt: string;
+        debugFile?: string;
     }, teammate: TeammateConfig, options: CliProxyOptions): string[];
     /** Extra env vars to set (e.g. FORCE_COLOR) */
     env?: Record<string, string>;
@@ -34,6 +52,8 @@ export interface AgentPreset {
     shell?: boolean;
     /** Whether to pipe the prompt via stdin instead of as a CLI argument */
     stdinPrompt?: boolean;
+    /** Whether this preset supports a debug log file (--debug-file) */
+    supportsDebugFile?: boolean;
     /** Optional output parser — transforms raw stdout into clean agent output */
     parseOutput?(raw: string): string;
 }

package/dist/adapters/cli-proxy.js

@@ -16,22 +16,26 @@
  */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { mkdirSync } from "node:fs";
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { buildTeammatePrompt } from "../adapter.js";
+import { buildTeammatePrompt, queryRecallContext } from "../adapter.js";
 export const PRESETS = {
     claude: {
         name: "claude",
         command: "claude",
-        buildArgs(_ctx, _teammate, options) {
+        buildArgs(ctx, _teammate, options) {
             const args = ["-p", "--verbose", "--dangerously-skip-permissions"];
             if (options.model)
                 args.push("--model", options.model);
+            if (ctx.debugFile)
+                args.push("--debug-file", ctx.debugFile);
             return args;
         },
         env: { FORCE_COLOR: "1", CLAUDECODE: "" },
         stdinPrompt: true,
+        supportsDebugFile: true,
     },
     codex: {
         name: "codex",
@@ -136,12 +140,31 @@ export class CliProxyAdapter {
         // If the teammate has no soul (e.g. the raw agent), skip identity/memory
         // wrapping but include handoff instructions so it can delegate to teammates
         const sessionFile = this.sessionFiles.get(teammate.name);
+        // Read session file content for injection into the prompt
+        let sessionContent;
+        if (sessionFile) {
+            try {
+                sessionContent = await readFile(sessionFile, "utf-8");
+            }
+            catch {
+                // Session file may not exist yet — that's fine
+            }
+        }
         let fullPrompt;
         if (teammate.soul) {
+            // Query recall for relevant memories before building prompt
+            const teammatesDir = teammate.cwd
+                ? join(teammate.cwd, ".teammates")
+                : undefined;
+            const recall = teammatesDir
+                ? await queryRecallContext(teammatesDir, teammate.name, prompt)
+                : undefined;
             fullPrompt = buildTeammatePrompt(teammate, prompt, {
                 roster: this.roster,
                 services: this.services,
                 sessionFile,
+                sessionContent,
+                recallResults: recall?.results,
             });
         }
         else {
@@ -167,12 +190,20 @@ export class CliProxyAdapter {
         await writeFile(promptFile, fullPrompt, "utf-8");
         this.pendingTempFiles.add(promptFile);
         try {
-            const rawOutput = await this.spawnAndProxy(teammate, promptFile, fullPrompt);
+            const spawn = await this.spawnAndProxy(teammate, promptFile, fullPrompt);
             const output = this.preset.parseOutput
-                ? this.preset.parseOutput(rawOutput)
-                : rawOutput;
+                ? this.preset.parseOutput(spawn.output)
+                : spawn.output;
             const teammateNames = this.roster.map((r) => r.name);
-            return parseResult(teammate.name, output, teammateNames, prompt);
+            const result = parseResult(teammate.name, output, teammateNames, prompt);
+            result.diagnostics = {
+                exitCode: spawn.exitCode,
+                signal: spawn.signal,
+                stderr: spawn.stderr,
+                timedOut: spawn.timedOut,
+                debugFile: spawn.debugFile,
+            };
+            return result;
         }
         finally {
             this.pendingTempFiles.delete(promptFile);
@@ -291,8 +322,21 @@ export class CliProxyAdapter {
      */
     spawnAndProxy(teammate, promptFile, fullPrompt) {
         return new Promise((resolve, reject) => {
+            // Always generate a debug log file for presets that support it (e.g. Claude's --debug-file).
+            // Written to .teammates/.tmp/debug/ so startup maintenance can clean old logs.
+            let debugFile;
+            if (this.preset.supportsDebugFile) {
+                const debugDir = join(teammate.cwd ?? process.cwd(), ".teammates", ".tmp", "debug");
+                try {
+                    mkdirSync(debugDir, { recursive: true });
+                }
+                catch {
+                    /* best effort */
+                }
+                debugFile = join(debugDir, `agent-${teammate.name}-${Date.now()}.log`);
+            }
             const args = [
-                ...this.preset.buildArgs({ promptFile, prompt: fullPrompt }, teammate, this.options),
+                ...this.preset.buildArgs({ promptFile, prompt: fullPrompt, debugFile }, teammate, this.options),
                 ...(this.options.extraFlags ?? []),
             ];
             const command = this.options.commandPath ?? this.preset.command;
@@ -352,12 +396,13 @@ export class CliProxyAdapter {
                 process.stdin.resume();
                 process.stdin.on("data", onUserInput);
             }
-            const captured = [];
+            const stdoutBufs = [];
+            const stderrBufs = [];
             child.stdout?.on("data", (chunk) => {
-                captured.push(chunk);
+                stdoutBufs.push(chunk);
             });
             child.stderr?.on("data", (chunk) => {
-                captured.push(chunk);
+                stderrBufs.push(chunk);
             });
             const cleanup = () => {
                 clearTimeout(timeoutTimer);
@@ -367,15 +412,22 @@ export class CliProxyAdapter {
                     process.stdin.removeListener("data", onUserInput);
                 }
             };
-            child.on("close", (_code) => {
+            child.on("close", (code, signal) => {
                 cleanup();
-                const output = Buffer.concat(captured).toString("utf-8");
-                if (killed) {
-                    resolve(`${output}\n\n[TIMEOUT] Agent process killed after ${timeout}ms`);
-                }
-                else {
-                    resolve(output);
-                }
+                const stdout = Buffer.concat(stdoutBufs).toString("utf-8");
+                const stderr = Buffer.concat(stderrBufs).toString("utf-8");
+                const output = stdout + (stderr ? `\n${stderr}` : "");
+                resolve({
+                    output: killed
+                        ? `${output}\n\n[TIMEOUT] Agent process killed after ${timeout}ms`
+                        : output,
+                    stdout,
+                    stderr,
+                    exitCode: code,
+                    signal: signal ?? null,
+                    timedOut: killed,
+                    debugFile,
+                });
             });
             child.on("error", (err) => {
                 cleanup();

package/dist/adapters/copilot.js

@@ -12,7 +12,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { approveAll, CopilotClient, } from "@github/copilot-sdk";
-import { buildTeammatePrompt } from "../adapter.js";
+import { buildTeammatePrompt, queryRecallContext } from "../adapter.js";
 import { parseResult } from "./cli-proxy.js";
 // ─── Adapter ─────────────────────────────────────────────────────────
 let nextId = 1;
@@ -59,13 +59,32 @@ export class CopilotAdapter {
     async executeTask(_sessionId, teammate, prompt) {
         await this.ensureClient(teammate.cwd);
         const sessionFile = this.sessionFiles.get(teammate.name);
+        // Read session file content for injection into the prompt
+        let sessionContent;
+        if (sessionFile) {
+            try {
+                sessionContent = await readFile(sessionFile, "utf-8");
+            }
+            catch {
+                // Session file may not exist yet — that's fine
+            }
+        }
         // Build the full teammate prompt (identity + memory + task)
         let fullPrompt;
         if (teammate.soul) {
+            // Query recall for relevant memories before building prompt
+            const teammatesDir = teammate.cwd
+                ? join(teammate.cwd, ".teammates")
+                : undefined;
+            const recall = teammatesDir
+                ? await queryRecallContext(teammatesDir, teammate.name, prompt)
+                : undefined;
             fullPrompt = buildTeammatePrompt(teammate, prompt, {
                 roster: this.roster,
                 services: this.services,
                 sessionFile,
+                sessionContent,
+                recallResults: recall?.results,
             });
         }
         else {