@adecore/agents 0.48.3 → 0.49.0

package/dist/chat/claude-backend.js

@@ -3,6 +3,7 @@ import { errorText } from '../error-text.js';
 import { claudeArgs, claudeEnv, promptPrefix } from '../providers/claude.js';
 import { ChatChild, MAX_LINE_LENGTH, readStreamLines } from './chat-process.js';
 import { ClaudeProtocol } from './claude-protocol.js';
+import { claudeSystemPromptArgs } from './claude-system-prompt.js';
 import { buildUserMessage } from './input.js';
 // Claude may echo a steer only once a slow tool returns, so a running turn sets no deadline; after the turn ended, a message
 // it still holds opens the next turn at once or never arrives.
@@ -57,7 +58,12 @@ export class ClaudeBackend {
             })
         ];
         if (this.launch.instructions !== null) {
-            args.push('--append-system-prompt', this.launch.instructions);
+            try {
+                args.push(...claudeSystemPromptArgs(this.launch.instructions));
+            }
+            catch (error) {
+                return Promise.reject(error instanceof Error ? error : new Error(errorText(error)));
+            }
         }
         this.stdinClosed = false;
         const child = new ChatChild({

package/dist/chat/claude-protocol.js

@@ -22,6 +22,12 @@ function taskUsage(usage) {
 function contextTokens(usage) {
     return isRecord(usage) ? num(usage.input_tokens) + num(usage.cache_creation_input_tokens) + num(usage.cache_read_input_tokens) : 0;
 }
+/*
+ * Claude Code 2.1.312 says `completed` for a subagent that stopped to wait on its own background work, and
+ * notifies the same task again when it reports. No field tells them apart: `handback` is also absent from a
+ * subagent that does not report through `SubagentHandback`, and `background_tasks_changed` drops the agent too.
+ */
+const INTERIM_TASK_SUMMARY = 'This agent has not reported yet';
 // How long a prompt cache entry lives, by the field of `usage.cache_creation` that counts what a request wrote with it.
 const CACHE_TTL_MS = { ephemeral_5m_input_tokens: 5 * 60_000, ephemeral_1h_input_tokens: 60 * 60_000 };
 /*
@@ -409,10 +415,20 @@ export class ClaudeProtocol {
         }
         else if (frame.subtype === 'task_notification') {
             const ref = str(frame.tool_use_id);
+            const taskId = str(frame.task_id);
+            if (str(frame.status) === 'completed' && str(frame.summary)?.startsWith(INTERIM_TASK_SUMMARY)) {
+                // `task_updated` already took it off the list of running agents.
+                if (taskId) {
+                    this.backgroundAgents.add(taskId);
+                }
+                if (ref) {
+                    events.push({ type: 'task.progress', ref, taskId, summary: null, lastTool: null, usage: taskUsage(frame.usage) });
+                }
+                return;
+            }
             if (ref) {
                 this.subagentModels.delete(ref);
             }
-            const taskId = str(frame.task_id);
             if (taskId) {
                 this.endBackground(taskId, events);
                 this.workflows.delete(taskId);

package/dist/chat/claude-system-prompt.d.ts

@@ -0,0 +1 @@
+export declare function claudeSystemPromptArgs(instructions: string, platform?: NodeJS.Platform, folder?: string): string[];

package/dist/chat/claude-system-prompt.js

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/*
+ * The flags that hand Claude its system prompt. npm installs the CLI as a batch file on Windows, and
+ * a line through cmd.exe holds no line break and stops near 8 KB, so there the prompt goes in a file.
+ * The name follows the content, so chats with the same prompt share one file and no chat removes it from under another.
+ */
+export function claudeSystemPromptArgs(instructions, platform = process.platform, folder = tmpdir()) {
+    if (platform !== 'win32') {
+        return ['--append-system-prompt', instructions];
+    }
+    const digest = createHash('sha256').update(instructions).digest('hex').slice(0, 32);
+    const path = join(folder, `adecore-claude-prompt-${digest}.md`);
+    writeFileSync(path, instructions, { mode: 0o600 });
+    return ['--append-system-prompt-file', path];
+}

package/dist/chat/codex-backend.js

@@ -146,7 +146,7 @@ export class CodexBackend {
             result = await transport.request('thread/start', { ...params, ...instructions });
         }
         this.imageInputSupported = await this.readImageSupport(transport);
-        for (const event of this.protocol.threadReady(result)) {
+        for (const event of this.protocol.threadReady(result, params.sandbox)) {
             if (event.type === 'session' && event.agentSessionId) {
                 this.threadId = event.agentSessionId;
             }
@@ -213,6 +213,15 @@ export class CodexBackend {
         return [...textInput(parts.join('')), ...images.map((attachment) => ({ type: 'localImage', path: attachment.path }))];
     }
     sendTurn(input) {
+        // TUI menus are not model instructions; explain the missing host flow instead of spending a turn on it.
+        if (this.transport &&
+            input.attachments.length === 0 &&
+            input.mentions.length === 0 &&
+            input.skills.length === 0 &&
+            /^\/usage(?:[ \t]+[^\r\n]*)?$/.test(input.text.trim())) {
+            this.reply(input.promptId, 'This chat does not support the /usage menu. Open Codex in a terminal and run /usage to view account activity or use an available earned rate-limit reset.');
+            return;
+        }
         const command = input.attachments.length === 0 ? parseGoalCommand(input.text) : null;
         if (command !== null) {
             void this.runGoalCommand(command, input);

package/dist/chat/codex-protocol.d.ts

@@ -24,7 +24,7 @@ export declare class CodexProtocol {
     private readonly agentRows;
     constructor(generation: number);
     get turnId(): string | null;
-    threadReady(result: unknown): BackendEvent[];
+    threadReady(result: unknown, askedSandbox?: string): BackendEvent[];
     handle(frame: CodexFrame): BackendEvent[];
     approvalDecision(requestId: string, decision: ApprovalDecision): {
         rpcId: CodexRpcId;

package/dist/chat/codex-protocol.js

@@ -57,6 +57,7 @@ function textOf(content) {
         .filter((text) => text !== null)
         .join('\n');
 }
+const SANDBOX_NOT_SET_UP = "Codex's sandbox is not set up here, so it can only read and asks before each command. Run `codex` once in a terminal to set it up.";
 // What `agentsStates` says of an agent that stopped working; the call that reports it may have completed long before.
 const ENDED_AGENT_STATES = new Set(['completed', 'errored', 'interrupted', 'shutdown', 'notFound']);
 /* What became of every agent a collab call touched, one line each; empty while the call still runs. */
@@ -189,7 +190,7 @@ export class CodexProtocol {
         return this.codexTurnId;
     }
     /* The result of `thread/start` or `thread/resume`. The thread id is what a terminal resumes. */
-    threadReady(result) {
+    threadReady(result, askedSandbox) {
         const thread = isRecord(result) && isRecord(result.thread) ? result.thread : {};
         this.ownThreadId = str(thread.id) ?? this.ownThreadId;
         const policy = isRecord(result) ? str(result.approvalPolicy) : null;
@@ -203,7 +204,11 @@ export class CodexProtocol {
                 title: cleanTitle(thread.name),
                 ...(policy && sandbox ? { permissionMode: `${policy} / ${sandbox}` } : {}),
                 ...(effectiveRuntimeMode === undefined ? {} : { effectiveRuntimeMode })
-            }
+            },
+            // On Windows a sandbox that was never set up leaves a thread read-only without an error, and the question that sets it up lives in Codex's TUI.
+            ...(askedSandbox === 'workspace-write' && sandbox === 'readOnly'
+                ? [{ type: 'note', level: 'warning', text: SANDBOX_NOT_SET_UP }]
+                : [])
         ];
     }
     handle(frame) {

package/dist/testing/fake-claude.js

@@ -3,7 +3,7 @@
  * compaction, edits, subagents, interrupts and crashes through the real frame shapes.
  */
 import { spawn } from 'node:child_process';
-import { writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 export function fakeClaude(io) {
     const args = io.argv;
@@ -938,7 +938,8 @@ export function fakeClaude(io) {
         }
         if (text === 'system?') {
             const at = args.indexOf('--append-system-prompt');
-            assistantText(at >= 0 ? args[at + 1] : 'none');
+            const fileAt = args.indexOf('--append-system-prompt-file');
+            assistantText(at >= 0 ? args[at + 1] : fileAt >= 0 ? readFileSync(args[fileAt + 1], 'utf8') : 'none');
             result();
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.48.3",
+  "version": "0.49.0",
   "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
   "type": "module",
   "exports": {
@@ -93,8 +93,8 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.48.3",
-    "@adecore/intelligent-ui": "0.48.3",
+    "@adecore/agent-contracts": "0.49.0",
+    "@adecore/intelligent-ui": "0.49.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {

package/src/chat/claude-backend.ts

@@ -4,6 +4,7 @@ import { claudeArgs, claudeEnv, promptPrefix } from '../providers/claude.ts';
 import type { ApprovalDecision, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
 import { ChatChild, MAX_LINE_LENGTH, readStreamLines } from './chat-process.ts';
 import { ClaudeProtocol } from './claude-protocol.ts';
+import { claudeSystemPromptArgs } from './claude-system-prompt.ts';
 import { buildUserMessage } from './input.ts';
 
 // Claude may echo a steer only once a slow tool returns, so a running turn sets no deadline; after the turn ended, a message
@@ -72,7 +73,11 @@ export class ClaudeBackend implements ChatBackend {
         ];
 
         if (this.launch.instructions !== null) {
-            args.push('--append-system-prompt', this.launch.instructions);
+            try {
+                args.push(...claudeSystemPromptArgs(this.launch.instructions));
+            } catch (error) {
+                return Promise.reject(error instanceof Error ? error : new Error(errorText(error)));
+            }
         }
 
         this.stdinClosed = false;

package/src/chat/claude-protocol.ts

@@ -41,6 +41,13 @@ function contextTokens(usage: unknown): number {
     return isRecord(usage) ? num(usage.input_tokens) + num(usage.cache_creation_input_tokens) + num(usage.cache_read_input_tokens) : 0;
 }
 
+/*
+ * Claude Code 2.1.312 says `completed` for a subagent that stopped to wait on its own background work, and
+ * notifies the same task again when it reports. No field tells them apart: `handback` is also absent from a
+ * subagent that does not report through `SubagentHandback`, and `background_tasks_changed` drops the agent too.
+ */
+const INTERIM_TASK_SUMMARY = 'This agent has not reported yet';
+
 // How long a prompt cache entry lives, by the field of `usage.cache_creation` that counts what a request wrote with it.
 const CACHE_TTL_MS: Record<string, number> = { ephemeral_5m_input_tokens: 5 * 60_000, ephemeral_1h_input_tokens: 60 * 60_000 };
 
@@ -511,13 +518,25 @@ export class ClaudeProtocol {
             }
         } else if (frame.subtype === 'task_notification') {
             const ref = str(frame.tool_use_id);
+            const taskId = str(frame.task_id);
+
+            if (str(frame.status) === 'completed' && str(frame.summary)?.startsWith(INTERIM_TASK_SUMMARY)) {
+                // `task_updated` already took it off the list of running agents.
+                if (taskId) {
+                    this.backgroundAgents.add(taskId);
+                }
+
+                if (ref) {
+                    events.push({ type: 'task.progress', ref, taskId, summary: null, lastTool: null, usage: taskUsage(frame.usage) });
+                }
+
+                return;
+            }
 
             if (ref) {
                 this.subagentModels.delete(ref);
             }
 
-            const taskId = str(frame.task_id);
-
             if (taskId) {
                 this.endBackground(taskId, events);
                 this.workflows.delete(taskId);

package/src/chat/claude-system-prompt.ts

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/*
+ * The flags that hand Claude its system prompt. npm installs the CLI as a batch file on Windows, and
+ * a line through cmd.exe holds no line break and stops near 8 KB, so there the prompt goes in a file.
+ * The name follows the content, so chats with the same prompt share one file and no chat removes it from under another.
+ */
+export function claudeSystemPromptArgs(instructions: string, platform: NodeJS.Platform = process.platform, folder: string = tmpdir()): string[] {
+    if (platform !== 'win32') {
+        return ['--append-system-prompt', instructions];
+    }
+
+    const digest = createHash('sha256').update(instructions).digest('hex').slice(0, 32);
+    const path = join(folder, `adecore-claude-prompt-${digest}.md`);
+
+    writeFileSync(path, instructions, { mode: 0o600 });
+
+    return ['--append-system-prompt-file', path];
+}

package/src/chat/codex-backend.ts

@@ -180,7 +180,7 @@ export class CodexBackend implements ChatBackend {
 
         this.imageInputSupported = await this.readImageSupport(transport);
 
-        for (const event of this.protocol.threadReady(result)) {
+        for (const event of this.protocol.threadReady(result, params.sandbox)) {
             if (event.type === 'session' && event.agentSessionId) {
                 this.threadId = event.agentSessionId;
             }
@@ -264,6 +264,22 @@ export class CodexBackend implements ChatBackend {
     }
 
     sendTurn(input: TurnInput): void {
+        // TUI menus are not model instructions; explain the missing host flow instead of spending a turn on it.
+        if (
+            this.transport &&
+            input.attachments.length === 0 &&
+            input.mentions.length === 0 &&
+            input.skills.length === 0 &&
+            /^\/usage(?:[ \t]+[^\r\n]*)?$/.test(input.text.trim())
+        ) {
+            this.reply(
+                input.promptId,
+                'This chat does not support the /usage menu. Open Codex in a terminal and run /usage to view account activity or use an available earned rate-limit reset.'
+            );
+
+            return;
+        }
+
         const command = input.attachments.length === 0 ? parseGoalCommand(input.text) : null;
 
         if (command !== null) {

package/src/chat/codex-protocol.ts

@@ -83,6 +83,8 @@ function textOf(content: unknown): string {
         .join('\n');
 }
 
+const SANDBOX_NOT_SET_UP = "Codex's sandbox is not set up here, so it can only read and asks before each command. Run `codex` once in a terminal to set it up.";
+
 // What `agentsStates` says of an agent that stopped working; the call that reports it may have completed long before.
 const ENDED_AGENT_STATES = new Set(['completed', 'errored', 'interrupted', 'shutdown', 'notFound']);
 
@@ -259,7 +261,7 @@ export class CodexProtocol {
     }
 
     /* The result of `thread/start` or `thread/resume`. The thread id is what a terminal resumes. */
-    threadReady(result: unknown): BackendEvent[] {
+    threadReady(result: unknown, askedSandbox?: string): BackendEvent[] {
         const thread = isRecord(result) && isRecord(result.thread) ? result.thread : {};
         this.ownThreadId = str(thread.id) ?? this.ownThreadId;
         const policy = isRecord(result) ? str(result.approvalPolicy) : null;
@@ -274,7 +276,11 @@ export class CodexProtocol {
                 title: cleanTitle(thread.name),
                 ...(policy && sandbox ? { permissionMode: `${policy} / ${sandbox}` } : {}),
                 ...(effectiveRuntimeMode === undefined ? {} : { effectiveRuntimeMode })
-            }
+            },
+            // On Windows a sandbox that was never set up leaves a thread read-only without an error, and the question that sets it up lives in Codex's TUI.
+            ...(askedSandbox === 'workspace-write' && sandbox === 'readOnly'
+                ? [{ type: 'note' as const, level: 'warning' as const, text: SANDBOX_NOT_SET_UP }]
+                : [])
         ];
     }
 

package/src/testing/fake-claude.ts

@@ -3,7 +3,7 @@
  * compaction, edits, subagents, interrupts and crashes through the real frame shapes.
  */
 import { spawn } from 'node:child_process';
-import { writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { FakeCli, FakeIo, FakeProgram } from './fake-cli.ts';
 
@@ -1113,7 +1113,8 @@ export function fakeClaude(io: FakeIo): FakeProgram {
 
         if (text === 'system?') {
             const at = args.indexOf('--append-system-prompt');
-            assistantText(at >= 0 ? args[at + 1]! : 'none');
+            const fileAt = args.indexOf('--append-system-prompt-file');
+            assistantText(at >= 0 ? args[at + 1]! : fileAt >= 0 ? readFileSync(args[fileAt + 1]!, 'utf8') : 'none');
             result();
 
             return;