@claxedo/agent-runtime-contract 0.8.0 → 0.10.1

package/dist/turn-fold.d.ts

@@ -0,0 +1,111 @@
+import { type AgentAssistantMessage, type AgentContentPart } from "./content";
+export type PartRef = {
+    messageId: string;
+    partId: string;
+};
+type WorkGroupTool = "bash" | "edit" | "webfetch";
+export type PartGroup = {
+    key: string;
+    type: "part";
+    ref: PartRef;
+    answer?: true;
+} | {
+    key: string;
+    type: "context";
+    refs: PartRef[];
+} | {
+    key: string;
+    type: "work";
+    tool: WorkGroupTool;
+    refs: PartRef[];
+} | {
+    key: string;
+    type: "agents";
+    refs: PartRef[];
+};
+type GroupablePart = {
+    messageId: string;
+    part: AgentContentPart;
+};
+export declare const EDIT_TOOL_NAMES: Set<string>;
+export declare const WEB_TOOL_NAMES: Set<string>;
+export declare function textIsPresent(text: string): boolean;
+export declare function partHasText(part: object): boolean;
+export declare function isHiddenTool(part: {
+    type: string;
+    tool?: string;
+}): boolean;
+export declare function isPendingQuestion(part: {
+    type: string;
+    tool?: string;
+    state?: {
+        status?: string;
+    };
+}): boolean;
+export declare function isSubagentToolPart(part: {
+    type: string;
+    tool?: string;
+    state?: {
+        input?: unknown;
+    };
+}): boolean;
+export declare function isGroupablePart(part: AgentContentPart, hasText: (part: AgentContentPart) => boolean, showReasoning: boolean): boolean;
+export declare function groupParts(input: GroupablePart[]): PartGroup[];
+export type FoldablePartLookup = (ref: PartRef) => FoldablePart | undefined;
+type FoldablePart = {
+    type: string;
+    userOpen?: boolean;
+};
+export declare function assistantMessageSettled(message: AgentAssistantMessage): boolean;
+export declare function answerPartRefs(groups: readonly PartGroup[], part: FoldablePartLookup): PartRef[];
+export declare function countFoldableGroups(groups: readonly PartGroup[], part: FoldablePartLookup): number;
+type TurnFoldStatus = {
+    foldableCount: number;
+    settled: boolean;
+    interrupted?: boolean;
+    errored?: boolean;
+    busy?: boolean;
+    foldWhenSettled?: boolean;
+    userChoice?: boolean;
+};
+type TurnFoldDecision = {
+    canFold: boolean;
+    folded: boolean;
+    explicit: boolean;
+};
+export declare function turnFoldDecision(status: TurnFoldStatus): TurnFoldDecision;
+export declare function groupMembers(group: PartGroup): PartRef[];
+export declare function foldedGroupKeys(decision: TurnFoldDecision, groups: readonly PartGroup[], part: FoldablePartLookup): ReadonlySet<string>;
+type TurnPartRef = GroupablePart & {
+    messageIndex: number;
+};
+type TurnFoldShape = {
+    /** The assistant message the turn was interrupted at, or -1. */
+    interruptedMessageIndex: number;
+    /** The interruption is the message's own abort error rather than the runtime's cancelled outcome. */
+    harnessInterrupted: boolean;
+    /** The message that failed the turn; an abort is an interruption, not a failure. */
+    errorMessage: AgentAssistantMessage | undefined;
+    settled: boolean;
+    compaction: boolean;
+    refs: TurnPartRef[];
+};
+/** The assistant message a session's last turn was cancelled at, which that turn draws as an interruption. */
+export declare function cancelledAssistantMessageId(lastTurn: {
+    status: string;
+    assistantMessageId?: string;
+} | undefined): string | undefined;
+export declare function turnInterruption(messages: readonly AgentAssistantMessage[], cancelledAssistantMessageId?: string): {
+    index: number;
+    harness: boolean;
+};
+export declare function turnFoldShape(input: {
+    assistantMessages: readonly AgentAssistantMessage[];
+    partsOf: (messageId: string) => readonly AgentContentPart[];
+    hasText: (part: AgentContentPart) => boolean;
+    showReasoning: boolean;
+    compaction: boolean;
+    cancelledAssistantMessageId?: string;
+}): TurnFoldShape;
+export declare function turnSegments(refs: readonly TurnPartRef[], shape: Pick<TurnFoldShape, "interruptedMessageIndex" | "compaction">): PartGroup[][];
+export {};

package/dist/turn-fold.mjs

@@ -0,0 +1,414 @@
+// ../claxedo-helpers/src/guards.ts
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asRecord(value) {
+  return isRecord(value) ? value : undefined;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function nonEmptyString(value) {
+  return isNonEmptyString(value) ? value : undefined;
+}
+
+// src/tool-names.ts
+var TOOL_NAME_ALIASES = {
+  agent: "task",
+  subagent: "task",
+  spawn_agent: "task",
+  spawnagent: "task",
+  create_subagent: "task",
+  mcp__claxedo__create_subagent: "task",
+  claxedo_create_subagent: "task",
+  command: "bash",
+  shell: "bash",
+  local_shell: "bash",
+  read_file: "read",
+  write_file: "write",
+  edit_file: "edit",
+  ls: "list",
+  askuserquestion: "question",
+  createplan: "exitplanmode",
+  web_search: "websearch"
+};
+function canonicalToolName(name) {
+  const lowered = name.toLowerCase();
+  return Object.hasOwn(TOOL_NAME_ALIASES, lowered) ? TOOL_NAME_ALIASES[lowered] : lowered;
+}
+var CLAXEDO_MCP_SERVER = "claxedo";
+var CLAXEDO_TOOL_NAMES = [
+  "task_list",
+  "task_get",
+  "task_create",
+  "task_edit",
+  "task_start",
+  "session_create",
+  "sessions_list",
+  "session_get",
+  "session_transcript",
+  "session_send",
+  "session_cancel_turn",
+  "session_handoff",
+  "session_rename",
+  "session_delete",
+  "session_changes",
+  "documents_list",
+  "documents_open",
+  "subagent_capabilities",
+  "create_subagent",
+  "subagent_status",
+  "subagent_list",
+  "subagent_cancel",
+  "sessions_board",
+  "permission_reply",
+  "question_reply",
+  "question_reject",
+  "wait_for_attention",
+  "workspaces_list",
+  "workspace_status",
+  "workspace_checkpoint",
+  "workspace_restore",
+  "workspace_lifecycle",
+  "app_plugin_create",
+  "app_plugin_check",
+  "app_plugin_add",
+  "app_plugin_guide",
+  "ui_show",
+  "ui_guide"
+];
+var CLAXEDO_TOOL_NAME_SET = new Set(CLAXEDO_TOOL_NAMES);
+function isClaxedoToolName(name) {
+  return CLAXEDO_TOOL_NAME_SET.has(name);
+}
+function claxedoToolName(tool, input) {
+  const lowered = tool.toLowerCase();
+  for (const server of ["claxedo-mcp", CLAXEDO_MCP_SERVER]) {
+    const wrapped = `mcp__${server}__`;
+    if (lowered.startsWith(wrapped))
+      return lowered.slice(wrapped.length) || undefined;
+    const joined = `${server}_`;
+    if (lowered.startsWith(joined)) {
+      const name = lowered.slice(joined.length);
+      if (isClaxedoToolName(name) || server === "claxedo-mcp" && name)
+        return name;
+    }
+    if (typeof input?.server === "string" && input.server.toLowerCase() === server) {
+      return nonEmptyString(input.tool)?.toLowerCase() ?? lowered;
+    }
+  }
+  return;
+}
+
+// src/transcript-notice.ts
+var SEVERITIES = new Set(["info", "warn", "error"]);
+
+// src/content.ts
+function isSubagentSpawnToolName(toolName) {
+  return canonicalToolName(toolName) === "task";
+}
+var FILE_PART_URL_SCHEMES = new Set(["data", "file", "http", "https"]);
+
+// src/turn-fold.ts
+var CONTEXT_GROUP_TOOLS = new Set(["read", "glob", "grep", "list"]);
+var STANDALONE_TOOLS = new Set(["question"]);
+var EDIT_TOOL_NAMES = new Set(["edit", "write", "apply_patch"]);
+var WEB_TOOL_NAMES = new Set(["webfetch", "websearch"]);
+var HIDDEN_TOOLS = new Set(["todowrite"]);
+var ANSWER_TOOLS = new Set(["ui_show"]);
+var GROUPABLE_PART_TYPES = new Set(["compaction", "handoff", "notice", "text", "reasoning", "tool", "file"]);
+var NON_BLANK = /\S/;
+function textIsPresent(text) {
+  return NON_BLANK.test(text);
+}
+function partHasText(part) {
+  return "text" in part && typeof part.text === "string" && textIsPresent(part.text);
+}
+function isHiddenTool(part) {
+  return part.type === "tool" && !!part.tool && HIDDEN_TOOLS.has(canonicalToolName(part.tool));
+}
+function producedImage(part) {
+  const state = part.state;
+  if (state.status !== "completed")
+    return false;
+  return !!state.attachments?.some((file) => file.mime.startsWith("image/"));
+}
+function isStandaloneTool(part) {
+  return part.type === "tool" && !!part.tool && STANDALONE_TOOLS.has(canonicalToolName(part.tool));
+}
+function isPendingQuestion(part) {
+  if (!isStandaloneTool(part))
+    return false;
+  const status = part.state?.status;
+  return status === "pending" || status === "running";
+}
+function isContextGroupTool(part) {
+  if (part.type !== "tool" || !CONTEXT_GROUP_TOOLS.has(canonicalToolName(part.tool)))
+    return false;
+  return !isClaxedoToolPart(part) && !producedImage(part);
+}
+function isWorkGroupTool(part) {
+  if (part.type !== "tool")
+    return false;
+  if (CONTEXT_GROUP_TOOLS.has(canonicalToolName(part.tool)) || isHiddenTool(part) || isStandaloneTool(part))
+    return false;
+  return !isSubagentToolPart(part) && !isClaxedoToolPart(part);
+}
+function isClaxedoToolPart(part) {
+  if (part.type !== "tool" || !part.tool)
+    return false;
+  return claxedoToolName(part.tool, asRecord(part.state?.input)) !== undefined;
+}
+function isAnswerToolPart(part) {
+  if (part.type !== "tool")
+    return false;
+  return ANSWER_TOOLS.has(claxedoToolName(part.tool, asRecord(part.state.input)) ?? "");
+}
+function isSubagentToolPart(part) {
+  if (part.type !== "tool")
+    return false;
+  if (part.tool && isSubagentSpawnToolName(part.tool))
+    return true;
+  const input = part.state?.input;
+  return typeof input === "object" && input !== null && input.intent === "task";
+}
+function spawnFailed(part) {
+  return part.type === "tool" && part.state.status === "error";
+}
+function isGroupablePart(part, hasText, showReasoning) {
+  if (part.type === "tool") {
+    if (isHiddenTool(part))
+      return false;
+    return !isPendingQuestion(part);
+  }
+  if (part.type === "text")
+    return hasText(part);
+  if (part.type === "reasoning")
+    return showReasoning && hasText(part);
+  return GROUPABLE_PART_TYPES.has(part.type);
+}
+function partRef(item) {
+  return { messageId: item.messageId, partId: item.part.id };
+}
+function workGroupTool(slice) {
+  if (slice.some((item) => item.part.type === "tool" && EDIT_TOOL_NAMES.has(canonicalToolName(item.part.tool))))
+    return "edit";
+  if (slice.some((item) => item.part.type === "tool" && WEB_TOOL_NAMES.has(canonicalToolName(item.part.tool))))
+    return "webfetch";
+  return "bash";
+}
+function partGroup(item) {
+  const group = { key: `part:${item.messageId}:${item.part.id}`, type: "part", ref: partRef(item) };
+  return isAnswerToolPart(item.part) ? { ...group, answer: true } : group;
+}
+function groupParts(input) {
+  const parts = input.filter((item) => !isPendingQuestion(item.part));
+  const result = [];
+  let contextStart = -1;
+  let workStart = -1;
+  let taskStart = -1;
+  let thoughtStart = -1;
+  const flushContext = (end) => {
+    if (contextStart < 0)
+      return;
+    const first = parts[contextStart];
+    if (!first) {
+      contextStart = -1;
+      return;
+    }
+    result.push({
+      key: `context:${first.part.id}`,
+      type: "context",
+      refs: parts.slice(contextStart, end + 1).map(partRef)
+    });
+    contextStart = -1;
+  };
+  const flushWork = (end) => {
+    if (workStart < 0)
+      return;
+    const slice = parts.slice(workStart, end + 1);
+    const first = parts[workStart];
+    if (!first) {
+      workStart = -1;
+      return;
+    }
+    if (slice.filter((item) => item.part.type === "tool").length >= 2) {
+      result.push({
+        key: `work:${first.part.id}`,
+        type: "work",
+        tool: workGroupTool(slice),
+        refs: slice.map(partRef)
+      });
+    } else {
+      result.push(...slice.map(partGroup));
+    }
+    workStart = -1;
+  };
+  const flushTask = (end) => {
+    if (taskStart < 0)
+      return;
+    const slice = parts.slice(taskStart, end + 1);
+    const first = parts[taskStart];
+    if (!first) {
+      taskStart = -1;
+      return;
+    }
+    result.push({ key: `agents:${first.part.id}`, type: "agents", refs: slice.map(partRef) });
+    taskStart = -1;
+  };
+  const flushThoughts = (end) => {
+    if (thoughtStart < 0)
+      return;
+    result.push(...parts.slice(thoughtStart, end + 1).map(partGroup));
+    thoughtStart = -1;
+  };
+  parts.forEach((item, index) => {
+    if (item.part.type === "reasoning") {
+      if (thoughtStart < 0)
+        thoughtStart = index;
+      return;
+    }
+    const runStart = thoughtStart < 0 ? index : thoughtStart;
+    const isContext = isContextGroupTool(item.part);
+    const isWork = isWorkGroupTool(item.part);
+    const isTask = !isClaxedoToolPart(item.part) && isSubagentToolPart(item.part) && !spawnFailed(item.part);
+    if (isContext) {
+      flushWork(runStart - 1);
+      flushTask(runStart - 1);
+      if (contextStart < 0)
+        contextStart = runStart;
+      thoughtStart = -1;
+      return;
+    }
+    if (isWork) {
+      flushContext(runStart - 1);
+      flushTask(runStart - 1);
+      if (workStart < 0)
+        workStart = runStart;
+      thoughtStart = -1;
+      return;
+    }
+    flushContext(runStart - 1);
+    flushWork(runStart - 1);
+    if (!isTask || thoughtStart >= 0)
+      flushTask(runStart - 1);
+    flushThoughts(index - 1);
+    if (isTask) {
+      if (taskStart < 0)
+        taskStart = index;
+      return;
+    }
+    result.push(partGroup(item));
+  });
+  const runEnd = (thoughtStart < 0 ? parts.length : thoughtStart) - 1;
+  flushContext(runEnd);
+  flushWork(runEnd);
+  flushTask(runEnd);
+  flushThoughts(parts.length - 1);
+  return result;
+}
+var FOLD_MINIMUM = 2;
+var NO_KEYS = new Set;
+function assistantMessageSettled(message) {
+  return typeof message.time.completed === "number" || !!message.error;
+}
+function holdsTool(group, part) {
+  return group.type !== "part" || !group.answer && part(group.ref)?.type === "tool";
+}
+function answerGroups(groups, part) {
+  const lastTool = groups.findLastIndex((group) => holdsTool(group, part));
+  return groups.slice(lastTool + 1).filter((group) => group.type === "part" && part(group.ref)?.type === "text");
+}
+function answerGroupKeys(groups, part) {
+  return new Set(answerGroups(groups, part).map((group) => group.key));
+}
+function answerPartRefs(groups, part) {
+  return answerGroups(groups, part).flatMap(groupMembers);
+}
+function isFoldableGroup(group, part, answerKeys) {
+  if (group.type !== "part")
+    return true;
+  if (group.answer || answerKeys.has(group.key))
+    return false;
+  const resolved = part(group.ref);
+  if (!resolved)
+    return false;
+  return resolved.type === "text" || resolved.type === "reasoning" || resolved.type === "tool";
+}
+function countFoldableGroups(groups, part) {
+  const answerKeys = answerGroupKeys(groups, part);
+  return groups.reduce((count, group) => isFoldableGroup(group, part, answerKeys) ? count + 1 : count, 0);
+}
+function turnFoldDecision(status) {
+  const running = !!status.busy && !status.errored;
+  const canFold = !running && status.foldWhenSettled !== false && status.settled && status.foldableCount >= FOLD_MINIMUM;
+  const explainsItself = !!status.interrupted || !!status.errored;
+  return {
+    canFold,
+    folded: canFold ? status.userChoice ?? !explainsItself : false,
+    explicit: status.userChoice !== undefined
+  };
+}
+function groupMembers(group) {
+  return group.type === "part" ? [group.ref] : group.refs;
+}
+function foldedGroupKeys(decision, groups, part) {
+  if (!decision.folded)
+    return NO_KEYS;
+  const answerKeys = answerGroupKeys(groups, part);
+  return new Set(groups.filter((group) => isFoldableGroup(group, part, answerKeys) && (decision.explicit || !groupMembers(group).some((ref) => part(ref)?.userOpen))).map((group) => group.key));
+}
+function assistantMessageInterrupted(message) {
+  return message.error?.name === "MessageAbortedError";
+}
+function cancelledAssistantMessageId(lastTurn) {
+  return lastTurn?.status === "cancelled" ? lastTurn.assistantMessageId : undefined;
+}
+function turnInterruption(messages, cancelledAssistantMessageId2) {
+  const harnessIndex = messages.findIndex(assistantMessageInterrupted);
+  if (harnessIndex !== -1 || cancelledAssistantMessageId2 === undefined)
+    return { index: harnessIndex, harness: harnessIndex !== -1 };
+  return { index: messages.findIndex((message) => message.id === cancelledAssistantMessageId2), harness: false };
+}
+function turnFoldShape(input) {
+  const messages = input.assistantMessages;
+  const interruption = turnInterruption(messages, input.cancelledAssistantMessageId);
+  const interrupted = interruption.index !== -1;
+  return {
+    interruptedMessageIndex: interruption.index,
+    harnessInterrupted: interruption.harness,
+    errorMessage: messages.find((message) => message.error && message.error.name !== "MessageAbortedError"),
+    settled: messages.some(assistantMessageSettled),
+    compaction: input.compaction,
+    refs: messages.flatMap((message, messageIndex) => input.partsOf(message.id).filter((part) => isGroupablePart(part, input.hasText, input.showReasoning) && !(interrupted && part.type === "tool" && (part.state.status === "pending" || part.state.status === "running"))).map((part) => ({ messageId: message.id, messageIndex, part })))
+  };
+}
+function turnSegments(refs, shape) {
+  if (shape.interruptedMessageIndex === -1 || shape.compaction)
+    return [groupParts([...refs])];
+  return [
+    groupParts(refs.filter((ref) => ref.messageIndex <= shape.interruptedMessageIndex)),
+    groupParts(refs.filter((ref) => ref.messageIndex > shape.interruptedMessageIndex))
+  ];
+}
+export {
+  turnSegments,
+  turnInterruption,
+  turnFoldShape,
+  turnFoldDecision,
+  textIsPresent,
+  partHasText,
+  isSubagentToolPart,
+  isPendingQuestion,
+  isHiddenTool,
+  isGroupablePart,
+  groupParts,
+  groupMembers,
+  foldedGroupKeys,
+  countFoldableGroups,
+  cancelledAssistantMessageId,
+  assistantMessageSettled,
+  answerPartRefs,
+  WEB_TOOL_NAMES,
+  EDIT_TOOL_NAMES
+};

package/dist/turn-message-ids.d.ts

@@ -0,0 +1,16 @@
+/** The id of the reply that answers `userMessageId`. */
+export declare function assistantMessageIdForTurn(userMessageId: string): string;
+/**
+ * The user message `assistantMessageId` answers, or `undefined` when the id
+ * was not minted by {@link assistantMessageIdForTurn}. Callers that require a
+ * parent must treat `undefined` as a contract violation to report, never as a
+ * cue to invent one: an id outside the convention names no user message, and
+ * substituting the session's own id fabricates a turn that does not exist.
+ */
+export declare function userMessageIdForAssistantReply(assistantMessageId: string): string | undefined;
+/**
+ * Mints message ids that sort by creation time on the minting clock. Other
+ * minters (a task's first prompt, a subagent, a server-side `msg_<uuid>`) do
+ * not, so a reader orders a session's messages by `time.created`, not by id.
+ */
+export declare function createMessageIds(clock?: () => number): () => string;

package/dist/turn-outline.d.ts

@@ -0,0 +1,37 @@
+export declare const TURN_OUTLINE_LIMIT = 500;
+export declare const TURN_OUTLINE_SNIPPET_LENGTH = 120;
+/** One turn as a transcript's outline lists it: what a nav rail needs, read from the turn's user message alone. */
+export type TurnOutlineEntry = {
+    id: string;
+    createdAt: number;
+    title?: string;
+    user?: string;
+};
+/** The newest turns of a session, oldest first; `complete` is false when turns older than the window exist. */
+export type TurnOutline = {
+    turns: TurnOutlineEntry[];
+    complete: boolean;
+};
+export type OutlineUserRow = {
+    id: string;
+    created_at: number | null;
+    title: string | null;
+};
+export type OutlineTextRow = {
+    message_id: string;
+    text: string | null;
+    synthetic: number | null;
+    ignored: number | null;
+};
+/**
+ * The rows a store reads for the outline's window, all from its user messages:
+ * the users oldest first, and their text parts in transcript order, each
+ * already cut to the snippet length by the store.
+ */
+type OutlineRows = {
+    users: readonly OutlineUserRow[];
+    texts: readonly OutlineTextRow[];
+    complete: boolean;
+};
+export declare function foldTurnOutline(rows: OutlineRows, snippetLength?: number): TurnOutline;
+export {};

package/dist/turn-page.d.ts

@@ -0,0 +1,58 @@
+import type { AgentMessage } from "./content";
+import type { TurnOutline } from "./turn-outline";
+export declare const TURN_PAGE_TURN_CAP = 24;
+export declare const TURN_PAGE_BYTE_CAP: number;
+export type ReaderSettings = {
+    reasoning: boolean;
+    shell: boolean;
+    edit: boolean;
+};
+export type TurnPageQuery = ReaderSettings & {
+    rows: number;
+    cols: number;
+};
+export type TurnPageRequest = TurnPageQuery & {
+    /** The assistant message the session's last turn was cancelled at, which that turn draws as an interruption. */
+    cancelledAssistantMessageId?: string;
+    /** Read the turns before this cursor; absent reads from the newest turn. */
+    before?: string;
+};
+export type PageTurn = {
+    messages: AgentMessage[];
+    /** Pages back from this turn's user message; absent on a session's first turn. */
+    cursor?: string;
+};
+/** Consecutive turns of a session, oldest first; the first turn's cursor reads what comes before the page. */
+export type TurnPage = {
+    turns: PageTurn[];
+};
+export type FirstRead<Session> = {
+    session: Session;
+    outline: TurnOutline;
+    page?: TurnPage;
+};
+/** A read named some but not all of its query parameters, or one of them out of range; every producer answers it with a 400. */
+export declare class TurnPageQueryError extends Error {
+    readonly name = "TurnPageQueryError";
+}
+/** One whole turn ending before `before` (the newest turn without it), and the cursor at its user message when older turns exist. */
+export type TurnRead = (before?: string) => Promise<{
+    messages: AgentMessage[];
+    nextCursor?: string;
+}> | {
+    messages: AgentMessage[];
+    nextCursor?: string;
+};
+type Query = (name: string) => string | undefined;
+export declare function parseTurnPageQuery(query: Query): TurnPageQuery | undefined;
+export declare function parseOlderTurnPageQuery(query: Query): TurnPageQuery & {
+    before: string;
+};
+export declare function projectTurn(messages: AgentMessage[], settings: ReaderSettings): PageTurn;
+type LineRequest = Pick<TurnPageRequest, "cols" | "reasoning" | "cancelledAssistantMessageId">;
+/** An estimate for choosing how many turns a page sends, never a layout. */
+export declare function estimateTurnLines(messages: readonly AgentMessage[], request: LineRequest): number;
+/** The caps decide how many turns are sent; a message or part is never trimmed. */
+export declare function readTurnPage(read: TurnRead, request: TurnPageRequest): Promise<TurnPage>;
+export declare function readFirstRead<Session>(session: Session, outline: TurnOutline, read: TurnRead, request: TurnPageRequest | undefined): Promise<FirstRead<Session>>;
+export {};

package/dist/usage-streams.d.ts

@@ -0,0 +1,19 @@
+import type { RuntimeTokenUsage, RuntimeUsageObservation } from "./events";
+/**
+ * A turn's usage as independent streams: each scope's running usage, and the
+ * last observation each scope applied, so a re-emitted one is not applied twice.
+ * The turn's usage is the sum over every scope.
+ */
+export type UsageStreams = {
+    streams: Map<string, RuntimeTokenUsage>;
+    lastObservationKeys: Map<string, string>;
+};
+export declare function unknownTokenUsage(): RuntimeTokenUsage;
+export declare function addTokenUsage(previous: RuntimeTokenUsage, next: RuntimeTokenUsage): RuntimeTokenUsage;
+export declare function usageStreamsTotal(streams: ReadonlyMap<string, RuntimeTokenUsage>): RuntimeTokenUsage;
+export declare function usageObservationKey(observation: RuntimeUsageObservation): string;
+export declare function isRepeatedUsageObservation(state: UsageStreams, observation: RuntimeUsageObservation): boolean;
+/** Applies one observation to its scope; a repeat of the scope's last observation changes nothing and returns false. */
+export declare function recordUsageObservation(state: UsageStreams, observation: RuntimeUsageObservation): boolean;
+/** A turn's usage from its observations in the order they were reported. */
+export declare function foldUsageObservations(observations: Iterable<RuntimeUsageObservation>): RuntimeTokenUsage;

package/dist/vendor-body.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What a model vendor's response body is.
+ *
+ * Only a JSON document is the vendor API's own answer. An HTML document is the
+ * edge in front of the API refusing the client: chatgpt.com answers requests
+ * from Cloudflare Worker egress with Cloudflare's challenge page (403,
+ * text/html, "Please try again later", observed 2026-10-15), and that page says
+ * nothing about the credential, the model or the account's limits. Anything
+ * else is prose a gateway, SDK or harness wrote.
+ */
+export type VendorBody = {
+    kind: "api";
+    document: Record<string, unknown>;
+} | {
+    kind: "page";
+} | {
+    kind: "text";
+};
+export declare function vendorBody(text: string): VendorBody;
+/**
+ * The HTTP status a vendor answered, as pi-ai's error states it ("OpenAI API
+ * error (401): {…}") or an SDK's error leads with ("401 {…}", "401: …"): the
+ * one fact about a refusal that is the vendor's own and not prose around it.
+ */
+export declare function vendorHttpStatus(text: string): number | undefined;
+/**
+ * The turn error a harness reports in place of an edge's page. The page itself
+ * never reaches a transcript: it is kilobytes of markup, and its "try again
+ * later" reads as a rate limit it is not.
+ */
+export declare const EDGE_REFUSED_MESSAGE = "The model provider refused the connection from this host and answered with a block page instead of its API; the account itself was not refused";