@adecore/agents 0.0.1 → 0.17.0-beta.1

package/src/chat/fixtures/codex-0.159.2-native-interacted.json

@@ -0,0 +1,220 @@
+{
+  "version": "codex-cli 0.159.2",
+  "capturedAt": "2026-09-30",
+  "source": "Live app-server stdio. Root started one native child, waited for completion, then sent a follow-up to the same child and waited again. Only native activity frames retained.",
+  "rootThreadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+  "frames": [
+    {
+      "method": "item/started",
+      "params": {
+        "item": {
+          "type": "subAgentActivity",
+          "id": "call_k0Jt3qf9tgn9mI47m4IJUR33",
+          "kind": "started",
+          "agentThreadId": "01a0f1d3-101b-7122-bb83-37604ac8612c",
+          "agentPath": "/root/lifecycle_probe"
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d2-e4e5-7f23-bb50-dd2bf74d6d0d",
+        "startedAtMs": 1790763536427
+      },
+      "emittedAtMs": 1790763536427
+    },
+    {
+      "method": "item/completed",
+      "params": {
+        "item": {
+          "type": "subAgentActivity",
+          "id": "call_k0Jt3qf9tgn9mI47m4IJUR33",
+          "kind": "started",
+          "agentThreadId": "01a0f1d3-101b-7122-bb83-37604ac8612c",
+          "agentPath": "/root/lifecycle_probe"
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d2-e4e5-7f23-bb50-dd2bf74d6d0d",
+        "completedAtMs": 1790763536427
+      },
+      "emittedAtMs": 1790763536427
+    },
+    {
+      "method": "item/started",
+      "params": {
+        "item": {
+          "type": "collabAgentToolCall",
+          "id": "call_YtRZ7UDKyrnHgjoiR7IuFLSz",
+          "tool": "wait",
+          "status": "inProgress",
+          "senderThreadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+          "receiverThreadIds": [],
+          "prompt": null,
+          "model": null,
+          "reasoningEffort": null,
+          "agentsStates": {}
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d2-e4e5-7f23-bb50-dd2bf74d6d0d",
+        "startedAtMs": 1790763539654
+      },
+      "emittedAtMs": 1790763539654
+    },
+    {
+      "method": "item/started",
+      "params": {
+        "item": {
+          "type": "subAgentActivity",
+          "id": "subagent-completed-01a0f1d3-102b-7af0-9bcd-61b99f122d40",
+          "kind": "completed",
+          "agentThreadId": "01a0f1d3-101b-7122-bb83-37604ac8612c",
+          "agentPath": "/root/lifecycle_probe"
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d2-e4e5-7f23-bb50-dd2bf74d6d0d",
+        "startedAtMs": 1790763544490
+      },
+      "emittedAtMs": 1790763544490
+    },
+    {
+      "method": "item/completed",
+      "params": {
+        "item": {
+          "type": "subAgentActivity",
+          "id": "subagent-completed-01a0f1d3-102b-7af0-9bcd-61b99f122d40",
+          "kind": "completed",
+          "agentThreadId": "01a0f1d3-101b-7122-bb83-37604ac8612c",
+          "agentPath": "/root/lifecycle_probe"
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d2-e4e5-7f23-bb50-dd2bf74d6d0d",
+        "completedAtMs": 1790763544490
+      },
+      "emittedAtMs": 1790763544490
+    },
+    {
+      "method": "item/completed",
+      "params": {
+        "item": {
+          "type": "collabAgentToolCall",
+          "id": "call_YtRZ7UDKyrnHgjoiR7IuFLSz",
+          "tool": "wait",
+          "status": "completed",
+          "senderThreadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+          "receiverThreadIds": [],
+          "prompt": null,
+          "model": null,
+          "reasoningEffort": null,
+          "agentsStates": {}
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d2-e4e5-7f23-bb50-dd2bf74d6d0d",
+        "completedAtMs": 1790763544490
+      },
+      "emittedAtMs": 1790763544491
+    },
+    {
+      "method": "item/started",
+      "params": {
+        "item": {
+          "type": "subAgentActivity",
+          "id": "call_h6YPJZGuDhGHjLQJuLm6gMDK",
+          "kind": "interacted",
+          "agentThreadId": "01a0f1d3-101b-7122-bb83-37604ac8612c",
+          "agentPath": "/root/lifecycle_probe"
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d3-3a75-7201-90ce-6427a3cf6b3f",
+        "startedAtMs": 1790763552887
+      },
+      "emittedAtMs": 1790763552887
+    },
+    {
+      "method": "item/completed",
+      "params": {
+        "item": {
+          "type": "subAgentActivity",
+          "id": "call_h6YPJZGuDhGHjLQJuLm6gMDK",
+          "kind": "interacted",
+          "agentThreadId": "01a0f1d3-101b-7122-bb83-37604ac8612c",
+          "agentPath": "/root/lifecycle_probe"
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d3-3a75-7201-90ce-6427a3cf6b3f",
+        "completedAtMs": 1790763552887
+      },
+      "emittedAtMs": 1790763552888
+    },
+    {
+      "method": "item/started",
+      "params": {
+        "item": {
+          "type": "collabAgentToolCall",
+          "id": "call_aD4wqmZGY3JHHehDizgElfhK",
+          "tool": "wait",
+          "status": "inProgress",
+          "senderThreadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+          "receiverThreadIds": [],
+          "prompt": null,
+          "model": null,
+          "reasoningEffort": null,
+          "agentsStates": {}
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d3-3a75-7201-90ce-6427a3cf6b3f",
+        "startedAtMs": 1790763555263
+      },
+      "emittedAtMs": 1790763555263
+    },
+    {
+      "method": "item/started",
+      "params": {
+        "item": {
+          "type": "subAgentActivity",
+          "id": "subagent-completed-01a0f1d3-5077-7ab3-ab59-cdb575663b4f",
+          "kind": "completed",
+          "agentThreadId": "01a0f1d3-101b-7122-bb83-37604ac8612c",
+          "agentPath": "/root/lifecycle_probe"
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d3-3a75-7201-90ce-6427a3cf6b3f",
+        "startedAtMs": 1790763555749
+      },
+      "emittedAtMs": 1790763555749
+    },
+    {
+      "method": "item/completed",
+      "params": {
+        "item": {
+          "type": "subAgentActivity",
+          "id": "subagent-completed-01a0f1d3-5077-7ab3-ab59-cdb575663b4f",
+          "kind": "completed",
+          "agentThreadId": "01a0f1d3-101b-7122-bb83-37604ac8612c",
+          "agentPath": "/root/lifecycle_probe"
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d3-3a75-7201-90ce-6427a3cf6b3f",
+        "completedAtMs": 1790763555749
+      },
+      "emittedAtMs": 1790763555750
+    },
+    {
+      "method": "item/completed",
+      "params": {
+        "item": {
+          "type": "collabAgentToolCall",
+          "id": "call_aD4wqmZGY3JHHehDizgElfhK",
+          "tool": "wait",
+          "status": "completed",
+          "senderThreadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+          "receiverThreadIds": [],
+          "prompt": null,
+          "model": null,
+          "reasoningEffort": null,
+          "agentsStates": {}
+        },
+        "threadId": "01a0f1d2-e495-7fb0-bfbd-0756f51209c8",
+        "turnId": "01a0f1d3-3a75-7201-90ce-6427a3cf6b3f",
+        "completedAtMs": 1790763555750
+      },
+      "emittedAtMs": 1790763555750
+    }
+  ]
+}

package/src/chat/fixtures/codex-0.159.2-usage-windows.json

@@ -0,0 +1,74 @@
+{
+  "version": "codex-cli 0.159.2",
+  "capturedAt": "2026-09-30T11:27:21.868Z",
+  "captureKind": "live-successful-turn",
+  "model": "gpt-6-astra",
+  "rootThreadId": "01a0f211-a052-7861-9810-745bd09593bf",
+  "note": "The live quota was 16 percent. This capture contains no exhausted-window error or reset. Credit balances and individual spend controls are omitted.",
+  "frames": [
+    {
+      "method": "turn/started",
+      "params": {
+        "threadId": "01a0f211-a052-7861-9810-745bd09593bf",
+        "turn": {
+          "id": "01a0f211-a0be-7212-94c7-39a8244ce58a",
+          "items": [],
+          "itemsView": "notLoaded",
+          "status": "inProgress",
+          "error": null,
+          "startedAt": 1790767636,
+          "completedAt": null,
+          "durationMs": null
+        }
+      },
+      "emittedAtMs": 1790767636675
+    },
+    {
+      "method": "account/rateLimits/updated",
+      "params": {
+        "rateLimits": {
+          "limitId": "codex",
+          "limitName": null,
+          "normalModelSlug": null,
+          "primary": {
+            "usedPercent": 16,
+            "windowDurationMins": 10080,
+            "resetsAt": 1791055009
+          },
+          "secondary": null,
+          "spendControlReached": null,
+          "planType": "pro",
+          "rateLimitReachedType": null
+        }
+      },
+      "emittedAtMs": 1790767641124
+    },
+    {
+      "method": "turn/completed",
+      "params": {
+        "threadId": "01a0f211-a052-7861-9810-745bd09593bf",
+        "turn": {
+          "id": "01a0f211-a0be-7212-94c7-39a8244ce58a",
+          "items": [
+            {
+              "type": "agentMessage",
+              "id": "msg_08e94bd26f7f2173016abcf218e25c87d2baf065fccee1c83c",
+              "text": "PONG",
+              "phase": "final_answer",
+              "memoryCitation": null,
+              "delivery": null,
+              "questions": null
+            }
+          ],
+          "itemsView": "summary",
+          "status": "completed",
+          "error": null,
+          "startedAt": 1790767636,
+          "completedAt": 1790767641,
+          "durationMs": 4463
+        }
+      },
+      "emittedAtMs": 1790767641137
+    }
+  ]
+}

package/src/chat/input.ts

@@ -0,0 +1,89 @@
+import type { ChatAttachment } from '@adecore/agent-contracts';
+
+interface UserMessageInput {
+    promptId?: string;
+    text: string;
+    attachments?: ChatAttachment[];
+    // Written before the text, for what the CLI has no flag for (`ultrathink`).
+    prefix?: string;
+    // Skills the person picked with `$`; the CLI runs one, and only from its own last text block.
+    skills?: string[];
+}
+
+function isBoundary(char: string | undefined): boolean {
+    return char === undefined || /\s/.test(char);
+}
+
+function isTokenEnd(char: string | undefined): boolean {
+    return isBoundary(char) || /[.,;:!?)]/.test(char!);
+}
+
+/* Where a `$name` of a known skill sits in the text, as a whole token; -1 when it does not. */
+function findSkillToken(text: string, name: string, from: number): number {
+    const token = `$${name}`;
+    let index = text.indexOf(token, from);
+    while (index >= 0) {
+        if (isBoundary(text[index - 1]) && isTokenEnd(text[index + token.length])) {
+            return index;
+        }
+        index = text.indexOf(token, index + 1);
+    }
+    return -1;
+}
+
+/* The last `$name` in the text that names one of the skills, longest name first on a tie. */
+export function lastSkillToken(text: string, skills: string[]): { index: number; name: string } | null {
+    let best: { index: number; name: string } | null = null;
+    for (const name of [...new Set(skills)].sort((a, b) => b.length - a.length)) {
+        let index = findSkillToken(text, name, 0);
+        while (index >= 0) {
+            if (best === null || index > best.index) {
+                best = { index, name };
+            }
+            index = findSkillToken(text, name, index + 1);
+        }
+    }
+    return best;
+}
+
+/*
+ * The text blocks a prompt with skills becomes. Claude Code expands a skill only from a text block
+ * that starts with `/name` and is the last one in the message (verified against 2.1.267 with a
+ * skill that writes a marker file), so the last `$name` moves into a block of its own. Anything the
+ * person wrote before it stays a block in front, with the earlier `$x` written as `/x` so the model
+ * can still reach those through its Skill tool.
+ */
+export function splitSkillPrompt(text: string, skills: string[]): { lead: string; invocation: string | null } {
+    const last = lastSkillToken(text, skills);
+    if (last === null) {
+        return { lead: text, invocation: null };
+    }
+    const lead = text.slice(0, last.index).replace(/\$([A-Za-z][A-Za-z0-9_:-]*)/g, (match, name: string) => (skills.includes(name) ? `/${name}` : match));
+    const rest = text.slice(last.index + last.name.length + 1).replace(/^[ \t]+/, '');
+    return { lead: lead.trimEnd(), invocation: rest === '' ? `/${last.name}` : `/${last.name} ${rest}` };
+}
+
+/* Paths stay in the prompt so the agent can also edit or copy the original attachments. */
+export function attachmentNote(attachments: ChatAttachment[]): string {
+    return attachments.length === 0 ? '' : `Attached files:\n${attachments.map((attachment) => `- ${attachment.path} (${attachment.name})`).join('\n')}`;
+}
+
+/*
+ * The `user` frame the CLI reads on stdin. The message body is the Anthropic API shape: a content
+ * array of text blocks, which the CLI passes through unchanged (checked against claude 2.1.266).
+ * The attachments are named by path in the leading block, so the invocation of a skill stays last.
+ */
+export function buildUserMessage({ text, attachments = [], prefix = '', skills = [], promptId }: UserMessageInput): Record<string, unknown> {
+    const content: unknown[] = [];
+    const { lead, invocation } = splitSkillPrompt(text, skills);
+    const note = attachmentNote(attachments);
+    // The prefix must be the first thing the model reads, so it joins the leading block.
+    const prompt = [`${prefix}${lead}`.trimEnd(), note].filter((part) => part.trim() !== '').join('\n\n');
+    if (prompt !== '') {
+        content.push({ type: 'text', text: prompt });
+    }
+    if (invocation !== null) {
+        content.push({ type: 'text', text: invocation });
+    }
+    return { type: 'user', message: { role: 'user', content }, parent_tool_use_id: null, session_id: '', ...(promptId ? { uuid: promptId } : {}) };
+}

package/src/chat/limit-resume.ts

@@ -0,0 +1,74 @@
+import type { ChatItem, ChatTurnItem, ChatTurnLimit } from '@adecore/agent-contracts';
+
+/* How long the host waits before each next try of a turn that stopped on a limit; one more limited turn in a row than there are delays is an error like any other. */
+export const LIMIT_RETRY_DELAYS_MS: readonly number[] = [60_000, 5 * 60_000, 15 * 60_000];
+
+/* The last turn of a thread, when it stopped on a limit. */
+export function limitedTurn(items: readonly ChatItem[]): (ChatTurnItem & { limit: ChatTurnLimit }) | null {
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i]!;
+        if (item.kind === 'turn') {
+            return item.state === 'error' && item.limit !== undefined ? (item as ChatTurnItem & { limit: ChatTurnLimit }) : null;
+        }
+    }
+    return null;
+}
+
+/* How many turns in a row, up to and including this one, stopped on a limit: the tries a person did not step in between. */
+function limitedInARow(items: readonly ChatItem[], turn: ChatTurnItem): number {
+    let count = 0;
+    let seen = false;
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i]!;
+        if (item.kind !== 'turn') {
+            continue;
+        }
+        seen ||= item.id === turn.id;
+        if (!seen) {
+            continue;
+        }
+        if (item.state !== 'error' || item.limit === undefined) {
+            break;
+        }
+        count += 1;
+    }
+    return count;
+}
+
+/*
+ * When the host takes a limited turn up again, or null when it does not: a usage limit at its reset
+ * and an overload after 1, 5 and 15 minutes. A usage limit that holds past its reset waits those too,
+ * so a reset the plan did not keep never turns into a loop.
+ */
+export function limitResumeAt(items: readonly ChatItem[], turn: ChatTurnItem, now: number): number | null {
+    if (turn.state !== 'error' || turn.limit === undefined) {
+        return null;
+    }
+    const tries = limitedInARow(items, turn);
+    const delay = LIMIT_RETRY_DELAYS_MS[tries - 1];
+    if (delay === undefined) {
+        return null;
+    }
+    if (turn.limit.kind === 'overload') {
+        return now + delay;
+    }
+    if (turn.limit.resetsAt === undefined) {
+        return null;
+    }
+    return tries === 1 ? turn.limit.resetsAt : Math.max(turn.limit.resetsAt, now + delay);
+}
+
+/* The turn the host opens to take a limited one up again: what the CLI is told, and what a person reads above it. */
+export function limitResumeWake(kind: ChatTurnLimit['kind']): { text: string; label: string; note: string } {
+    return kind === 'usage'
+        ? {
+              text: 'Your previous turn stopped on a usage limit, which has reset now. Continue where you left off.',
+              label: 'Usage limit reset',
+              note: 'Resumed after the usage limit reset'
+          }
+        : {
+              text: 'Your previous turn stopped because the model was overloaded. Continue where you left off.',
+              label: 'Overloaded model',
+              note: 'Tried again after the model was overloaded'
+          };
+}