@adecore/agents 0.48.4 → 0.49.0

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.48.4",
+  "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.4",
-    "@adecore/intelligent-ui": "0.48.4",
+    "@adecore/agent-contracts": "0.49.0",
+    "@adecore/intelligent-ui": "0.49.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {

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/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 }]
+                : [])
         ];
     }