@sema-agent/client-core 0.94.0 → 0.96.0

package/dist/toolResult.js

@@ -3,6 +3,8 @@ import { markEngineWorkflowNotified, registerOutstandingBgTask, registerOutstand
 import { parseWorkflowPollEnvelope, projectWorkflowTaskOutput } from './workflow.js';
 import { asModelFallbackReason } from './engineErrorCodes.js';
 import { frozenSet } from './frozenSet.js';
+import { bashExitOf, bashExitReadingFailed } from './bashExitReading.js';
+import { isCoreSemaTaskTerminal } from './terminalStatuses.js';
 import { CORE_ENGINE_CARD_TYPES } from './generated/engineFactTables.js';
 export const STRUCTURED_DETAIL_TYPES = frozenSet(CORE_ENGINE_CARD_TYPES);
 export function structuredDetailType(structured) {
@@ -12,11 +14,6 @@ export function structuredDetailType(structured) {
     return typeof t === 'string' && STRUCTURED_DETAIL_TYPES.has(t) ? t : undefined;
 }
 const MAX_STRUCTURED_FIELD_CHARS = 1_000_000;
-const WF_TERMINAL_STATUSES = new Set([
-    'completed',
-    'failed',
-    'cancelled',
-]);
 export const PROTOCOL_MARKERS = {
     bashHead: /^exit code: (-?\d+)(?: \(([^)\n]*)\))?\n(--- stdout ---\n)?/,
     bashStderrSep: '\n--- stderr ---\n',
@@ -28,6 +25,7 @@ export const PROTOCOL_MARKERS = {
     delegationNoTextResult: '(no text result)',
     delegationTrailer: 'Verify this result before concluding. If it leaves more to do, continue or delegate again.',
     delegationTrailerFork: 'Verify this result before concluding. If it leaves more to do, continue the work yourself or fork again.',
+    delegationFieldLine: /^(status|error|error_kind|observer|stats|worktree):(?: ([^\r\u2028\u2029\u0085]*))?/,
     taskOutputLabel: /^TaskOutput\s+(\S+)$/,
     taskOutputStatus: /^status:\s*(.+)$/m,
     taskOutputHeadSlots: /^(\r?\n)(?:(state: ([^\r\n\u2028\u2029\u0085]*)(?:\r?\n|$)))?(?:(error: ([^\r\n\u2028\u2029\u0085]*)(?:\r?\n|$)))?/,
@@ -35,7 +33,7 @@ export const PROTOCOL_MARKERS = {
     taskOutputNoneSentinel: '(none)',
     taskOutputStdoutLine: /^--- (?:new )?stdout[^\n]*---\n?/m,
     taskOutputStderrLine: /^--- (?:new )?stderr[^\n]*---\n?/m,
-    taskOutputResultLine: /^--- result(?: \([^)\n]*\))? ---\n?/m,
+    taskOutputResultLine: /^--- result(?: \((?:[^)\n\r\u2028\u2029]|[\r\u2028\u2029](?!--- result))*\))? ---\n?/m,
     spoolStdoutFull: '--- stdout (full, re-readable) ---',
     spoolStdoutIncremental: '--- new stdout ---',
 };
@@ -78,6 +76,59 @@ export function stripUntrustedFence(text) {
         return null;
     return { label: m[1] ?? '', body: m[2] ?? '' };
 }
+function delegationFrameSlots(lines, headAt, labelAt, fromAt) {
+    const read = (i) => {
+        const line = lines[i] ?? '';
+        const hit = PROTOCOL_MARKERS.delegationFieldLine.exec(line);
+        if (hit === null)
+            return null;
+        const value = hit[2];
+        return { key: hit[1] ?? '', value: value !== undefined && hit[0].length === line.length && value.trim() !== '' ? value : undefined };
+    };
+    const fields = [];
+    for (let i = headAt + 1; i < labelAt; i++)
+        fields.push(read(i));
+    const errorFollowedByEngineField = (at) => {
+        const next = fields[at + 1];
+        return next !== null && next !== undefined && next.value !== undefined && (next.key === 'error_kind' || next.key === 'observer' || next.key === 'stats');
+    };
+    const worktreeBefore = (at) => fields.slice(0, at).some((f) => f?.key === 'worktree');
+    const soleAt = (key) => {
+        let at = -1;
+        for (let i = 0; i < fields.length; i++) {
+            if (fields[i]?.key !== key)
+                continue;
+            if (at >= 0)
+                return -1;
+            at = i;
+        }
+        return at;
+    };
+    const claimed = new Set([headAt, labelAt]);
+    if (fromAt > labelAt + 1)
+        claimed.add(labelAt + 1);
+    const slots = {};
+    const first = fields[0] ?? null;
+    if (first !== null && first.key === 'status' && first.value !== undefined && soleAt('status') === 0) {
+        slots.status = first.value.trim();
+        claimed.add(headAt + 1);
+        for (const key of ['error', 'stats']) {
+            const at = soleAt(key);
+            const value = at >= 0 ? fields[at]?.value : undefined;
+            if (value === undefined || (key === 'error' && (!errorFollowedByEngineField(at) || worktreeBefore(at))))
+                continue;
+            slots[key] = value;
+            claimed.add(headAt + 1 + at);
+        }
+    }
+    let rest = '';
+    for (let i = 0; i < fromAt; i++)
+        if (!claimed.has(i))
+            rest += `${lines[i] ?? ''}\n`;
+    if (rest.trim() !== '')
+        slots.headRest = rest;
+    return slots;
+}
 function locateDelegationResultSection(text) {
     const lines = text.split('\n');
     const soleLineAt = (hit) => {
@@ -107,14 +158,14 @@ function locateDelegationResultSection(text) {
     };
     if (trailerAt === labelAt + 2 && lines[labelAt + 1] === PROTOCOL_MARKERS.delegationNoTextResult) {
         const c = cut(labelAt + 1);
-        return { section: 'no_text_result', before: c.before, after: c.after };
+        return { section: 'no_text_result', before: c.before, after: c.after, slots: delegationFrameSlots(lines, headAt, labelAt, labelAt + 1) };
     }
     const partial = lines[labelAt + 1] === PROTOCOL_MARKERS.delegationPartialFindingsLabel;
     const from = partial ? labelAt + 2 : labelAt + 1;
     if (from >= trailerAt)
         return null;
     const c = cut(from);
-    return { section: partial ? 'partial_findings' : 'result', before: c.before, fenceText: c.middle, after: c.after };
+    return { section: partial ? 'partial_findings' : 'result', before: c.before, fenceText: c.middle, after: c.after, slots: delegationFrameSlots(lines, headAt, labelAt, from) };
 }
 export function displayBody(text, origin = 'any_tool_result') {
     if (typeof text !== 'string')
@@ -128,14 +179,14 @@ export function displayBody(text, origin = 'any_tool_result') {
     if (located === null)
         return { fenced: false, body: text };
     if (located.section === 'no_text_result') {
-        const { before, after, section } = located;
-        return { fenced: false, body: '', frame: { before, after, section } };
+        const { before, after, section, slots } = located;
+        return { fenced: false, body: '', frame: { before, after, section, ...slots } };
     }
     const inner = stripUntrustedFence(located.fenceText);
     if (inner === null)
         return { fenced: false, body: text };
-    const { before, after, section } = located;
-    return { fenced: true, label: inner.label, body: inner.body, frame: { before, after, section } };
+    const { before, after, section, slots } = located;
+    return { fenced: true, label: inner.label, body: inner.body, frame: { before, after, section, ...slots } };
 }
 export function parseModelFacingTaskOutput(text) {
     modelFacingParseCount++;
@@ -241,7 +292,7 @@ export function wireOutputToBody(toolName, output, isError, truncated, flatten,
                         : typeof bgBlock?.task_id === 'string'
                             ? bgBlock.task_id
                             : undefined;
-                if (s?.detached === true)
+                if (readBashDetachView(structured)?.handoffTaskId !== undefined)
                     bgTaskId = undefined;
             }
             else {
@@ -255,20 +306,23 @@ export function wireOutputToBody(toolName, output, isError, truncated, flatten,
                 };
             }
         }
-        const slots = sType === 'bash' && (typeof s?.stdout === 'string' || typeof s?.stderr === 'string')
+        let parsedMemo;
+        const parseOnce = () => (parsedMemo === undefined ? (parsedMemo = parseModelFacingBash(text)) : parsedMemo);
+        const exit = bashExitOf(structured, parseOnce);
+        const structuredSlots = sType === 'bash' && (typeof s?.stdout === 'string' || typeof s?.stderr === 'string');
+        const textSlots = structuredSlots ? null : parseOnce();
+        const slots = structuredSlots
             ? {
                 stdout: typeof s?.stdout === 'string' ? s.stdout : '',
                 stderr: typeof s?.stderr === 'string' ? s.stderr : '',
-                exitCode: typeof s?.exitCode === 'number' ? s.exitCode : null,
+                exitCode: exit.exitCode,
             }
-            : parseModelFacingBash(text);
+            : textSlots !== null
+                ? { ...textSlots, exitCode: exit.exitCode }
+                : null;
         if (slots) {
-            const benignInterp = typeof s?.returnCodeInterpretation === 'string' && s.returnCodeInterpretation.length > 0
-                ? s.returnCodeInterpretation
-                : 'note' in slots && typeof slots.note === 'string' && slots.note.length > 0
-                    ? slots.note
-                    : undefined;
-            const failed = isError || (slots.exitCode != null && slots.exitCode !== 0 && benignInterp === undefined);
+            const benignInterp = exit.benignNote;
+            const failed = isError || bashExitReadingFailed(exit);
             if (failed) {
                 const reason = slots.stderr.length > 0 ? slots.stderr : slots.stdout;
                 let body = slots.exitCode != null ? `Exit code ${slots.exitCode}\n${reason}` : reason;
@@ -293,7 +347,7 @@ export function wireOutputToBody(toolName, output, isError, truncated, flatten,
             };
         }
         const stdout = truncated ? `${text}\n…(truncated)` : text;
-        if (isError)
+        if (isError || bashExitReadingFailed(exit))
             return { content: stdout, isError: true };
         return { content: stdout, isError, toolUseResult: { stdout, stderr: '', interrupted: false } };
     }
@@ -301,8 +355,9 @@ export function wireOutputToBody(toolName, output, isError, truncated, flatten,
         const body = truncated ? `${text}\n…(truncated)` : text;
         const parsed = parseModelFacingTaskOutput(text);
         const wrap = (task) => ({
-            content: { retrieval_status: 'success', task },
+            content: body,
             isError,
+            toolUseResult: { retrieval_status: 'success', task },
         });
         if (parsed.kind === 'agent') {
             return wrap({
@@ -316,7 +371,7 @@ export function wireOutputToBody(toolName, output, isError, truncated, flatten,
         }
         const wfEnvelope = parseWorkflowPollEnvelope(text);
         if (wfEnvelope) {
-            if (leaderLedger && WF_TERMINAL_STATUSES.has(wfEnvelope.status))
+            if (leaderLedger && isCoreSemaTaskTerminal(wfEnvelope.status))
                 markEngineWorkflowNotified(wfEnvelope.taskId);
             return wrap({
                 task_id: wfEnvelope.taskId,
@@ -362,23 +417,22 @@ export function structuredToToolUseResult(structured, modelText, leaderLedger =
             };
         }
         case 'bash': {
-            if (s.detached === true && typeof s.task_id === 'string') {
+            const handoffTaskId = readBashDetachView(structured)?.handoffTaskId;
+            if (handoffTaskId !== undefined) {
                 return {
                     toolUseResult: {
                         stdout: '',
                         stderr: '',
                         interrupted: false,
-                        backgroundTaskId: s.task_id,
+                        backgroundTaskId: handoffTaskId,
                         backgroundedByUser: true,
                     },
                 };
             }
             if (typeof s.stdout !== 'string' && typeof s.stderr !== 'string')
                 return null;
-            const exitCode = typeof s.exitCode === 'number' ? s.exitCode : null;
-            const benignInterp = typeof s.returnCodeInterpretation === 'string' && s.returnCodeInterpretation.length > 0
-                ? s.returnCodeInterpretation
-                : undefined;
+            const exit = bashExitOf(structured, () => null);
+            const benignInterp = exit.benignNote;
             return {
                 toolUseResult: {
                     stdout: typeof s.stdout === 'string' ? s.stdout : '',
@@ -386,7 +440,7 @@ export function structuredToToolUseResult(structured, modelText, leaderLedger =
                     interrupted: false,
                     ...(benignInterp !== undefined ? { returnCodeInterpretation: benignInterp } : {}),
                 },
-                ...(exitCode !== null && exitCode !== 0 && benignInterp === undefined ? { isError: true } : {}),
+                ...(bashExitReadingFailed(exit) ? { isError: true } : {}),
             };
         }
         case 'edit': {
@@ -650,7 +704,7 @@ export function structuredToToolUseResult(structured, modelText, leaderLedger =
             const runErrorCode = typeof s.errorCode === 'string' && s.errorCode.length > 0 ? s.errorCode : undefined;
             let output = bodyText ?? '';
             if (taskType === 'workflow') {
-                if (leaderLedger && WF_TERMINAL_STATUSES.has(status))
+                if (leaderLedger && isCoreSemaTaskTerminal(status))
                     markEngineWorkflowNotified(taskId);
                 const jsonSrc = output.length > 0 ? output : (modelText ?? '');
                 output = projectWorkflowTaskOutput(jsonSrc);
@@ -716,9 +770,9 @@ export function detectEngineBgShellDetach(toolName, rawInput, structured, output
     if (toolName !== 'Bash')
         return null;
     const view = readBashDetachView(structured);
-    if (view === null || !view.detached || view.registerFailed || view.taskId === undefined)
+    if (view === null || view.registerFailed || view.handoffTaskId === undefined)
         return null;
-    return engineBgShellRegistrationBody(view.taskId, rawInput, typeof outputText === 'string' ? outputText : '', 'bash');
+    return engineBgShellRegistrationBody(view.handoffTaskId, rawInput, typeof outputText === 'string' ? outputText : '', 'bash');
 }
 function readBashDetachView(structured) {
     if (typeof structured !== 'object' || structured === null)
@@ -731,9 +785,8 @@ function readBashDetachView(structured) {
     const registerFailed = s.registerFailed;
     const taskId = s.task_id;
     return {
-        detached: detached === true,
+        handoffTaskId: detached === true && typeof taskId === 'string' && taskId.length > 0 ? taskId : undefined,
         registerFailed: registerFailed === true,
-        taskId: typeof taskId === 'string' && taskId.length > 0 ? taskId : undefined,
     };
 }
 export function todoWriteToolUseResult(rawInput, oldTodos, isError) {

package/dist/toolResultContent.d.ts

@@ -0,0 +1,2 @@
+export declare function toolResultBlocksOf(output: unknown, truncated: boolean): unknown[] | undefined;
+export declare function toolEndOutputText(output: unknown): string | undefined;

package/dist/toolResultContent.js

@@ -0,0 +1,63 @@
+const IMAGE_MEDIA_TYPES = Object.freeze(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
+const OMITTED_CONTENT_NOTE = '[unsupported content omitted]';
+const IMAGE_TEXT_PLACEHOLDER = '[image]';
+function blockOf(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const b = raw;
+    if (b.type === 'text')
+        return typeof b.text === 'string' ? { type: 'text', text: b.text } : null;
+    if (b.type !== 'image')
+        return null;
+    const data = b.data;
+    const mediaType = b.mimeType;
+    if (typeof data !== 'string')
+        return null;
+    if (typeof mediaType !== 'string' || !IMAGE_MEDIA_TYPES.includes(mediaType))
+        return null;
+    return { type: 'image', source: { type: 'base64', media_type: mediaType, data } };
+}
+const TRUNCATED_NOTE = '…(truncated)';
+function toolResultContentOf(output) {
+    if (typeof output === 'string')
+        return output;
+    if (!Array.isArray(output))
+        return undefined;
+    const blocks = [];
+    let omitted = 0;
+    let images = 0;
+    for (const raw of output) {
+        const block = blockOf(raw);
+        if (block === null)
+            omitted++;
+        else {
+            if (block.type === 'image')
+                images++;
+            blocks.push(block);
+        }
+    }
+    if (images === 0 && omitted === 0)
+        return blocks.map((b) => b.text).join('');
+    if (omitted > 0)
+        blocks.push({ type: 'text', text: OMITTED_CONTENT_NOTE });
+    return blocks;
+}
+export function toolResultBlocksOf(output, truncated) {
+    const content = toolResultContentOf(output);
+    if (!Array.isArray(content))
+        return undefined;
+    if (truncated)
+        content.push({ type: 'text', text: TRUNCATED_NOTE });
+    return content;
+}
+export function toolEndOutputText(output) {
+    const content = toolResultContentOf(output);
+    if (content === undefined || typeof content === 'string')
+        return content;
+    return content
+        .map((b) => {
+        const block = b;
+        return block.type === 'image' ? IMAGE_TEXT_PLACEHOLDER : (block.text ?? '');
+    })
+        .join('');
+}

package/dist/types/engineState.d.ts

@@ -1,5 +1,5 @@
 import type { EngineHealth } from '@sema-agent/sdk';
-export interface HealthResponse extends Pick<EngineHealth, 'status' | 'model' | 'sessionBackend' | 'sessions' | 'instanceId' | 'dataRoot' | 'configHash' | 'pid' | 'port' | 'restartRequired' | 'version' | 'restart'> {
+export interface HealthResponse extends Pick<EngineHealth, 'status' | 'model' | 'sessionBackend' | 'sessions' | 'instanceId' | 'dataRoot' | 'configHash' | 'pid' | 'port' | 'restartRequired' | 'version' | 'startedAt'> {
 }
 export interface EnginePortFile {
     port: number;
@@ -19,6 +19,7 @@ export interface EngineInstance {
     instanceId?: string;
     dataRoot?: string;
     configHash?: string;
+    startedAt?: number;
     logPath?: string;
     ownedByThisShell: boolean;
     child?: unknown;

package/dist/usageAnalytics.d.ts

@@ -0,0 +1,146 @@
+import type { UsageAnalyticsParams, UsageBreakdown, UsageDimension, UsageGranularity, UsageMetric, UsageSeries, UsageSummary } from '@sema-agent/sdk';
+export declare const USAGE_SENTENCES: Readonly<{
+    analyticsUnavailable: "Usage analytics aren’t available on this backend.";
+    analyticsUnread: "Usage analytics couldn’t be read just now.";
+    modelsUnavailable: "Per-model usage breakdown isn't available on this backend.";
+    modelsUnread: "Per-model usage breakdown couldn’t be read just now.";
+}>;
+export interface UsageSummaryQuery extends UsageAnalyticsParams {
+    signal?: AbortSignal;
+}
+export interface UsageSeriesQuery extends UsageAnalyticsParams {
+    metric?: UsageMetric;
+    granularity?: UsageGranularity;
+    signal?: AbortSignal;
+}
+export interface UsageBreakdownQuery extends UsageAnalyticsParams {
+    dimension?: UsageDimension;
+    signal?: AbortSignal;
+}
+export interface UsageAnalyticsVerbs {
+    summary?: (opts?: UsageSummaryQuery) => Promise<UsageSummary>;
+    series?: (opts?: UsageSeriesQuery) => Promise<UsageSeries>;
+    breakdown?: (opts?: UsageBreakdownQuery) => Promise<UsageBreakdown>;
+}
+export interface UsageAnalyticsClientLike {
+    usage: UsageAnalyticsVerbs;
+}
+export interface UsageReadOptions {
+    from?: string | number;
+    to?: string | number;
+    principal?: string;
+    signal?: AbortSignal;
+}
+export interface UsageSeriesReadOptions extends UsageReadOptions {
+    metric?: UsageMetric;
+    granularity?: UsageGranularity;
+}
+export interface UsageBreakdownReadOptions extends UsageReadOptions {
+    dimension?: UsageDimension;
+}
+export type UsageBound = 'exact' | 'lower' | 'approximate';
+export type UsagePrecision = 'exact' | 'estimated';
+export interface UsageTotalsView {
+    tasks?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    cost?: number;
+    precision: UsagePrecision;
+}
+export interface UsageWindowView {
+    from?: string;
+    to?: string;
+    truncated: boolean;
+}
+export type UsageSummaryView = UsageWindowView & UsageTotalsView;
+export interface UsageSeriesPointView {
+    t: string;
+    v: number;
+    estimated?: boolean;
+}
+export interface UsageSeriesView extends UsageWindowView {
+    points: UsageSeriesPointView[];
+    unreadable: number;
+}
+export type UsageBreakdownRowView = UsageTotalsView & {
+    key: string;
+};
+export interface UsageBreakdownView extends UsageWindowView {
+    rows: UsageBreakdownRowView[];
+    unreadable: number;
+}
+export type UsageUnavailableWhy = 'capability' | 'feature' | 'route';
+export type UsageReadVerdict<T> = {
+    readonly kind: 'ok';
+    readonly value: T;
+} | {
+    readonly kind: 'unavailable';
+    readonly why: UsageUnavailableWhy;
+} | {
+    readonly kind: 'failed';
+    readonly error: unknown;
+};
+export declare function classifyUsageFailure(e: unknown): UsageReadVerdict<never>;
+export declare function projectUsageSummary(body: unknown): UsageSummaryView | undefined;
+export declare function projectUsageSeries(body: unknown): UsageSeriesView | undefined;
+export declare function projectUsageBreakdown(body: unknown): UsageBreakdownView | undefined;
+export declare function readUsageSummary(client: UsageAnalyticsClientLike, opts?: UsageReadOptions): Promise<UsageReadVerdict<UsageSummaryView>>;
+export declare function readUsageSeries(client: UsageAnalyticsClientLike, opts?: UsageSeriesReadOptions): Promise<UsageReadVerdict<UsageSeriesView>>;
+export declare function readUsageBreakdown(client: UsageAnalyticsClientLike, opts?: UsageBreakdownReadOptions): Promise<UsageReadVerdict<UsageBreakdownView>>;
+export interface UsageAmount {
+    readonly value: number;
+    readonly bound: UsageBound;
+}
+export declare function usageBoundPrefix(bound: UsageBound): '' | '≥' | '≈';
+export interface UsageHeatmapCell {
+    readonly date: string;
+    readonly tasks: number;
+}
+export type UsageUnavailableCause = 'no_backend_face' | 'read_failed';
+export type UsageModelsView = {
+    readonly state: 'available';
+    readonly rows: readonly UsageBreakdownRowView[];
+    readonly unreadable: number;
+} | {
+    readonly state: 'unavailable';
+    readonly cause: UsageUnavailableCause;
+    readonly sentence: string;
+};
+export interface UsageAnalyticsReadings {
+    readonly state: 'available' | 'estimated';
+    readonly truncated: boolean;
+    readonly runs?: number;
+    readonly tokens?: UsageAmount;
+    readonly cost?: UsageAmount;
+    readonly activeDays?: number;
+    readonly peakHourUtc?: number;
+    readonly favoriteModel?: string;
+    readonly heatmap: readonly UsageHeatmapCell[] | null;
+    readonly models: UsageModelsView;
+}
+export interface UsageAnalyticsUnavailable {
+    readonly state: 'unavailable';
+    readonly cause: UsageUnavailableCause;
+    readonly sentence: string;
+    readonly models: Extract<UsageModelsView, {
+        state: 'unavailable';
+    }>;
+}
+export type UsageAnalyticsView = UsageAnalyticsReadings | UsageAnalyticsUnavailable;
+export interface UsageAnalyticsInputs {
+    summary: UsageReadVerdict<UsageSummaryView>;
+    daySeries: UsageReadVerdict<UsageSeriesView>;
+    hourSeries: UsageReadVerdict<UsageSeriesView>;
+    modelBreakdown: UsageReadVerdict<UsageBreakdownView>;
+}
+export interface UsageAnalyticsWindow {
+    readonly from: number;
+    readonly to: number;
+}
+export type UsageRange = 'all' | '30d' | '7d';
+export declare const USAGE_HEATMAP_MAX_DAYS = 70;
+export declare function usageWindowOfRange(range: UsageRange, now: number): UsageAnalyticsWindow;
+export declare function projectUsageAnalytics(inputs: UsageAnalyticsInputs, window: UsageAnalyticsWindow): UsageAnalyticsView;
+export declare function readUsageAnalytics(client: UsageAnalyticsClientLike, window: UsageAnalyticsWindow, opts?: {
+    signal?: AbortSignal;
+}): Promise<UsageAnalyticsView>;