@sema-agent/client-core 0.83.6 → 0.84.1

package/dist/adapter/downstream/eventToSdkMessage.js

@@ -3,14 +3,16 @@ import { stamp, snapshotSegmentIdentity, } from '../types.js';
 import { turnUsageToModelUsage } from './turnUsageToModelUsage.js';
 import { ccToolDenialKindForToolEnd, gateOutcomeOf } from '../../gateOutcome.js';
 import { projectToolRoster, projectToolRosterDelta } from '../../toolRoster.js';
+import { projectHandsSection } from '../../handsSeam.js';
 import { readMcpLiveness } from '../../mcpLiveness.js';
 import { SEGMENT_END_IDENTITY_KEYS } from '../types.js';
+import { frozenSet } from '../../frozenSet.js';
 function armBody(body) {
     return body;
 }
 const SUGGESTION_BATCH_CAP = 8;
 const SUGGESTION_CHARS_CAP = 200;
-export const INTERNAL_SDK_ARM_TYPES = new Set([
+export const INTERNAL_SDK_ARM_TYPES = frozenSet([
     'tool_disclosure',
     'tool_progress',
     'tool_roster_delta',
@@ -546,7 +548,8 @@ function wiringManifestSupersetBody(ev) {
     const writeProtection = projectWriteProtectionSection(ev.writeProtection);
     const autoConsolidation = projectAutoConsolidationSection(ev.autoConsolidation);
     const readDeny = projectReadDenySection(ev.readDeny);
-    if (modelGate === undefined && autoMode === undefined && mcp === undefined && tools === undefined && hooks === undefined && lsp === undefined && writeProtection === undefined && autoConsolidation === undefined && readDeny === undefined)
+    const hands = projectHandsSection(ev);
+    if (modelGate === undefined && autoMode === undefined && mcp === undefined && tools === undefined && hooks === undefined && lsp === undefined && writeProtection === undefined && autoConsolidation === undefined && readDeny === undefined && hands === undefined)
         return undefined;
     return {
         ...(modelGate !== undefined ? { _sema_modelGate: modelGate } : {}),
@@ -558,6 +561,7 @@ function wiringManifestSupersetBody(ev) {
         ...(writeProtection !== undefined ? { _sema_writeProtection: writeProtection } : {}),
         ...(autoConsolidation !== undefined ? { _sema_autoConsolidation: autoConsolidation } : {}),
         ...(readDeny !== undefined ? { _sema_readDeny: readDeny } : {}),
+        ...(hands !== undefined ? { _sema_hands: hands } : {}),
     };
 }
 function projectWriteProtectionSection(raw) {

package/dist/adapter/downstream/terminalToSdkResult.d.ts

@@ -30,6 +30,7 @@ export interface SemaPermissionDenial {
     readonly tool_use_id?: string;
     readonly tool_input?: Record<string, unknown>;
     readonly _sema_tool_input_source?: 'tool_start';
+    readonly _sema_tool_input_redacted?: true;
     readonly _sema_tool_arg?: string;
     readonly deniedBy?: DeniedBy;
     readonly _sema_denied_by_source?: 'tool_end';

package/dist/adapter/downstream/terminalToSdkResult.js

@@ -40,14 +40,15 @@ function joinableToolInput(args) {
     if (args === null || typeof args !== 'object' || Array.isArray(args))
         return undefined;
     let nodes = 0;
+    let transportRedacted = false;
     const stack = [{ v: args, depth: 0 }];
     while (stack.length > 0) {
         const { v, depth } = stack.pop();
         if (++nodes > TOOL_INPUT_SCAN_MAX_NODES || depth > TOOL_INPUT_SCAN_MAX_DEPTH)
             return undefined;
         if (typeof v === 'string') {
-            if (v.includes(REDACTION_MARKER_PREFIX) || isTransportPlaceholderLeaf(v))
-                return undefined;
+            if (!transportRedacted && (v.includes(REDACTION_MARKER_PREFIX) || isTransportPlaceholderLeaf(v)))
+                transportRedacted = true;
             continue;
         }
         if (v === null || typeof v !== 'object')
@@ -56,7 +57,7 @@ function joinableToolInput(args) {
         for (const c of children)
             stack.push({ v: c, depth: depth + 1 });
     }
-    return args;
+    return { input: args, transportRedacted };
 }
 const GATE_DENIED_DECISIONS = new Set(['deny']);
 const GATE_NON_DENIAL_DECISIONS = new Set(['allow', 'approve', 'edit', 'reject']);
@@ -92,9 +93,10 @@ function permissionDenialParts(stats, observed) {
         const ledgerInput = rawInput !== null && typeof rawInput === 'object' && !Array.isArray(rawInput)
             ? rawInput
             : undefined;
-        const joinedInput = ledgerInput === undefined && toolUseId !== undefined && toolInputByCallId?.has(toolUseId) === true
+        const joined = ledgerInput === undefined && toolUseId !== undefined && toolInputByCallId?.has(toolUseId) === true
             ? joinableToolInput(toolInputByCallId.get(toolUseId))
             : undefined;
+        const joinedInput = joined?.input;
         const toolInput = ledgerInput ?? joinedInput;
         const ledgerDeniedByRaw = row.deniedBy;
         const ledgerDeniedBy = typeof ledgerDeniedByRaw === 'string' && isGateDeniedByWord(ledgerDeniedByRaw)
@@ -116,6 +118,7 @@ function permissionDenialParts(stats, observed) {
             ...(toolUseId !== undefined ? { tool_use_id: toolUseId } : {}),
             ...(toolInput !== undefined ? { tool_input: toolInput } : {}),
             ...(joinedInput !== undefined ? { _sema_tool_input_source: 'tool_start' } : {}),
+            ...(joined?.transportRedacted === true ? { _sema_tool_input_redacted: true } : {}),
             ...(deniedBy !== undefined ? { deniedBy } : {}),
             ...(joinedDeniedBy !== undefined && ledgerDeniedBy === undefined
                 ? { _sema_denied_by_source: 'tool_end' }
@@ -145,7 +148,8 @@ function permissionDenialParts(stats, observed) {
                 continue;
             }
             const toolName = nonEmptyStr(toolNameRaw);
-            const joinedInput = toolInputByCallId?.has(callId) === true ? joinableToolInput(toolInputByCallId.get(callId)) : undefined;
+            const joined = toolInputByCallId?.has(callId) === true ? joinableToolInput(toolInputByCallId.get(callId)) : undefined;
+            const joinedInput = joined?.input;
             const deniedByRaw = gateDeniedByByCallId?.has(callId) === true ? gateDeniedByByCallId.get(callId) : undefined;
             const deniedBy = typeof deniedByRaw === 'string' && isGateDeniedByWord(deniedByRaw) ? deniedByRaw : undefined;
             const toolDenialKind = isCcToolDenialKind(mergedKind) ? mergedKind : undefined;
@@ -153,6 +157,7 @@ function permissionDenialParts(stats, observed) {
                 ...(toolName !== undefined ? { tool_name: toolName } : {}),
                 tool_use_id: callId,
                 ...(joinedInput !== undefined ? { tool_input: joinedInput, _sema_tool_input_source: 'tool_start' } : {}),
+                ...(joined?.transportRedacted === true ? { _sema_tool_input_redacted: true } : {}),
                 ...(deniedBy !== undefined ? { deniedBy, _sema_denied_by_source: 'tool_end' } : {}),
                 ...(toolDenialKind !== undefined ? { toolDenialKind } : {}),
             });

package/dist/adapter/downstream/wiringManifestView.d.ts

@@ -1,5 +1,5 @@
 import type { WiringManifestModelGate, WiringManifestAutoMode, WiringManifestMcpEntryView, WiringManifestHookEntryView, WiringManifestLspSeamView, WiringManifestWriteProtectionView, WiringManifestAutoConsolidationView, WiringManifestReadDenyView } from './eventToSdkMessage.js';
-import type { ToolRosterView } from '../../toolRoster.js';
+import type { ToolRosterView, WiringManifestHandsView } from '../../toolRoster.js';
 export type WiringManifestSections = {
     _sema_modelGate?: WiringManifestModelGate;
     _sema_autoMode?: WiringManifestAutoMode;
@@ -10,6 +10,7 @@ export type WiringManifestSections = {
     _sema_writeProtection?: WiringManifestWriteProtectionView;
     _sema_autoConsolidation?: WiringManifestAutoConsolidationView;
     _sema_readDeny?: WiringManifestReadDenyView;
+    _sema_hands?: WiringManifestHandsView;
     eventId?: string;
 };
 export interface WiringManifestView {
@@ -22,6 +23,7 @@ export interface WiringManifestView {
     writeProtection?: WiringManifestWriteProtectionView;
     autoConsolidation?: WiringManifestAutoConsolidationView;
     readDeny?: WiringManifestReadDenyView;
+    hands?: WiringManifestHandsView;
     eventId?: string;
 }
 export declare function wiringManifestViewOf(s: WiringManifestSections): WiringManifestView | undefined;

package/dist/adapter/downstream/wiringManifestView.js

@@ -14,6 +14,7 @@ export function wiringManifestViewOf(s) {
         ...(isObj(s._sema_writeProtection) ? { writeProtection: s._sema_writeProtection } : {}),
         ...(isObj(s._sema_autoConsolidation) ? { autoConsolidation: s._sema_autoConsolidation } : {}),
         ...(isObj(s._sema_readDeny) ? { readDeny: s._sema_readDeny } : {}),
+        ...(isObj(s._sema_hands) && typeof s._sema_hands.mounted === 'boolean' ? { hands: s._sema_hands } : {}),
     };
     if (Object.keys(view).length === 0)
         return undefined;

package/dist/agentSession/engineAgentRegistryRead.d.ts

@@ -0,0 +1,18 @@
+import type { AgentClient, Capabilities } from '@sema-agent/sdk';
+import type { EngineAgentRegistryListing, EngineAgentRegistryRowView } from '../engineAgentAbsence.js';
+export interface EngineAgentRegistryClient {
+    readonly sessions: Pick<AgentClient['sessions'], 'background'>;
+}
+export declare function registryClockNowMs(): number;
+export interface RegistryListingProvenance {
+    readonly superseded: boolean;
+    readonly sessionId: string;
+    readonly rows: readonly EngineAgentRegistryRowView[];
+    readonly rawRowCount: number;
+    firstSeenAtMs(id: string): number | undefined;
+}
+export declare function registryListingProvenanceOf(listing: EngineAgentRegistryListing | null | undefined): RegistryListingProvenance | undefined;
+export declare function isEngineAgentRegistryListingSuperseded(listing: EngineAgentRegistryListing | null | undefined): boolean;
+export declare function readEngineAgentRegistry(client: EngineAgentRegistryClient, sessionId: string, caps: Pick<Capabilities, 'background'> | null | undefined, opts?: {
+    readonly signal?: AbortSignal;
+}): Promise<EngineAgentRegistryListing>;

package/dist/agentSession/engineAgentRegistryRead.js

@@ -0,0 +1,167 @@
+import { errCodes } from '../controlRouter.js';
+import { hostLog } from '../host.js';
+const unavailable = (why) => ({
+    kind: 'unavailable',
+    why,
+});
+function noteReadFailed(cause, diag) {
+    try {
+        const bits = [
+            diag?.status !== undefined ? `status=${diag.status}` : '',
+            diag?.errorCode !== undefined ? `errorCode=${diag.errorCode}` : '',
+        ].filter((b) => b.length > 0);
+        hostLog('debug', `[sema][registry] read_failed (${cause})${bits.length > 0 ? ` ${bits.join(' ')}` : ''}`);
+    }
+    catch {
+    }
+}
+const readLedgers = new WeakMap();
+const listingRecords = new WeakMap();
+function ledgerFor(sessions, sessionId) {
+    let bySession = readLedgers.get(sessions);
+    if (bySession === undefined) {
+        bySession = new Map();
+        readLedgers.set(sessions, bySession);
+    }
+    let ledger = bySession.get(sessionId);
+    if (ledger === undefined) {
+        ledger = { issued: 0, deliveredMax: 0, firstSeen: new Map() };
+        bySession.set(sessionId, ledger);
+    }
+    return ledger;
+}
+export function registryClockNowMs() {
+    const p = globalThis.performance;
+    if (typeof p === 'object' && p !== null && typeof p.now === 'function' && typeof p.timeOrigin === 'number') {
+        const v = p.timeOrigin + p.now.call(p);
+        if (Number.isFinite(v))
+            return v;
+    }
+    return Date.now();
+}
+export function registryListingProvenanceOf(listing) {
+    if (typeof listing !== 'object' || listing === null)
+        return undefined;
+    const rec = listingRecords.get(listing);
+    if (rec === undefined)
+        return undefined;
+    return {
+        superseded: rec.ledger.deliveredMax > rec.seq,
+        sessionId: rec.sessionId,
+        rows: rec.rows,
+        rawRowCount: rec.rawRowCount,
+        firstSeenAtMs: (id) => rec.ledger.firstSeen.get(id),
+    };
+}
+export function isEngineAgentRegistryListingSuperseded(listing) {
+    return registryListingProvenanceOf(listing)?.superseded === true;
+}
+function listFaceOn(caps) {
+    if (typeof caps !== 'object' || caps === null || !Object.hasOwn(caps, 'background'))
+        return false;
+    const bg = caps.background;
+    if (typeof bg !== 'object' || bg === null || !Object.hasOwn(bg, 'listFace'))
+        return false;
+    return bg.listFace === true;
+}
+function readRow(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return undefined;
+    const o = v;
+    const id = Object.hasOwn(o, 'id') ? o.id : undefined;
+    const type = Object.hasOwn(o, 'type') ? o.type : undefined;
+    const status = Object.hasOwn(o, 'status') ? o.status : undefined;
+    if (typeof id !== 'string' || id.length === 0 || typeof type !== 'string' || type.length === 0 || typeof status !== 'string' || status.length === 0)
+        return undefined;
+    const description = Object.hasOwn(o, 'description') ? o.description : undefined;
+    const createdAt = Object.hasOwn(o, 'createdAt') ? o.createdAt : undefined;
+    return {
+        id,
+        type,
+        status,
+        ...(typeof description === 'string' && description.length > 0 ? { description } : {}),
+        ...(typeof createdAt === 'number' && Number.isFinite(createdAt) ? { createdAt } : {}),
+    };
+}
+export async function readEngineAgentRegistry(client, sessionId, caps, opts) {
+    try {
+        return await readOnce(client, sessionId, caps, opts);
+    }
+    catch {
+        noteReadFailed('reader threw');
+        return unavailable('read_failed');
+    }
+}
+async function readOnce(client, sessionId, caps, opts) {
+    if (!listFaceOn(caps))
+        return unavailable('no_list_face');
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        noteReadFailed('bad session id');
+        return unavailable('read_failed');
+    }
+    if (typeof client !== 'object' || client === null) {
+        noteReadFailed('bad client');
+        return unavailable('read_failed');
+    }
+    const sessions = client.sessions;
+    if (typeof sessions !== 'object' || sessions === null) {
+        noteReadFailed('bad client');
+        return unavailable('read_failed');
+    }
+    const ledger = ledgerFor(sessions, sessionId);
+    const seq = ++ledger.issued;
+    let body;
+    try {
+        const signal = opts?.signal;
+        body = await sessions.background(sessionId, signal !== undefined ? { signal } : undefined);
+    }
+    catch (e) {
+        const { code, status } = errCodes(e);
+        if (status === 404 && code === 'not_found.route')
+            return unavailable('route_absent');
+        if (status === 501 && code === 'capability.session_ownership_required')
+            return unavailable('ownership_required');
+        const diag = {
+            ...(typeof status === 'number' && Number.isInteger(status) ? { status } : {}),
+            ...(typeof code === 'string' && code.length > 0 ? { errorCode: code } : {}),
+        };
+        noteReadFailed('request failed', diag);
+        return { kind: 'unavailable', why: 'read_failed', ...diag };
+    }
+    if (typeof body !== 'object' || body === null || !Object.hasOwn(body, 'rows')) {
+        noteReadFailed('body is not { rows }');
+        return unavailable('read_failed');
+    }
+    const raw = body.rows;
+    if (!Array.isArray(raw)) {
+        noteReadFailed('body is not { rows }');
+        return unavailable('read_failed');
+    }
+    const rows = [];
+    for (const r of raw) {
+        const row = readRow(r);
+        if (row === undefined) {
+            noteReadFailed('a row could not be read');
+            return unavailable('read_failed');
+        }
+        rows.push(Object.freeze(row));
+    }
+    const rawRowCount = raw.length;
+    if (seq > ledger.deliveredMax) {
+        ledger.deliveredMax = seq;
+        const now = registryClockNowMs();
+        const present = new Set();
+        for (const row of rows) {
+            present.add(row.id);
+            if (!ledger.firstSeen.has(row.id))
+                ledger.firstSeen.set(row.id, now);
+        }
+        for (const id of [...ledger.firstSeen.keys()])
+            if (!present.has(id))
+                ledger.firstSeen.delete(id);
+    }
+    const frozenRows = Object.freeze(rows);
+    const listing = Object.freeze({ kind: 'rows', rows: frozenRows, sessionId, seq });
+    listingRecords.set(listing, { ledger, seq, sessionId, rows: frozenRows, rawRowCount });
+    return listing;
+}

package/dist/agentsWireCaps.js

@@ -1,5 +1,7 @@
 import { hostEnv } from './hostEnv.js';
 import { makeEngineWireClient } from './engineWireSdk.js';
+import { frozenSet } from './frozenSet.js';
+import { settleWithinDeadline } from './abortableSleep.js';
 export const MAX_TASK_AGENTS = 32;
 export const MAX_AGENT_NAME_CHARS = 64;
 export const MAX_AGENT_TEXT_CHARS = 4_096;
@@ -25,7 +27,7 @@ export const TASK_AGENT_WIRE_FIELDS = [
     'observer',
     'observerMessage',
 ];
-export const AGENT_MEMORY_WORDS = new Set(['user', 'project', 'local']);
+export const AGENT_MEMORY_WORDS = frozenSet(['user', 'project', 'local']);
 const SOURCE_RANK = {
     policySettings: 0,
     flagSettings: 1,
@@ -172,6 +174,13 @@ export function projectAgentsForWire(defs, deps) {
     return { agents: out.length > 0 ? out : undefined, warnings };
 }
 export async function engineSupportsTaskAgents(baseUrl, opts) {
+    if (opts?.client !== undefined) {
+        const injected = opts.client;
+        if (typeof injected?.capabilities !== 'function')
+            return undefined;
+        const got = await settleWithinDeadline(opts.timeoutMs ?? 3000, (signal) => injected.capabilities({ signal }));
+        return got.kind === 'value' ? got.value?.taskAgents === true : undefined;
+    }
     const client = makeEngineWireClient({
         baseUrl,
         ...(opts?.authToken ? { token: opts.authToken } : {}),

package/dist/attachmentsWireCaps.js

@@ -1,7 +1,7 @@
 import { hostEnv } from './hostEnv.js';
 import { envFlagOff } from './envFlag.js';
 export const ATTACHMENTS_ENV = 'SEMA_ATTACHMENTS';
-export const ATTACHMENTS_SPEC_KEYS = [
+export const ATTACHMENTS_SPEC_KEYS = Object.freeze([
     'todoReminder',
     'todoReminderMode',
     'changedFiles',
@@ -12,7 +12,7 @@ export const ATTACHMENTS_SPEC_KEYS = [
     'mcpInstructions',
     'agentListing',
     'skillsListing',
-];
+]);
 export const ATTACHMENTS_DEFAULT_ON_KEYS = ['agentListing', 'skillsListing', 'backgroundTasks'];
 const OPT_IN_KEYS = [
     'todoReminder',

package/dist/controlRouter.js

@@ -83,7 +83,7 @@ export class ControlRouter {
             }
             if (isCancelSuspendedConflict(e)) {
                 throw new ControlSafetyError('runs.cancel 409 — the pending gate was decided or expired concurrently (lost CAS race); ' +
-                    're-read the run state and retry cancel if it is still active', 'cancel_lost_race', e);
+                    'check what that decision did to the run before retrying the cancel', 'cancel_lost_race', e);
             }
             if (isNotFound(e)) {
                 throw new ControlSafetyError('runs.cancel 404 — non-owner / unknown run (no existence leak)', 'not_found', e);

package/dist/decideFailureNote.d.ts

@@ -1 +1,2 @@
-export declare function decideFailureNote(err: unknown): string;
+import { type ParkedResumeStartupDecision } from './resumeRefusalCopy.js';
+export declare function decideFailureNote(err: unknown, decision?: ParkedResumeStartupDecision): string;

package/dist/decideFailureNote.js

@@ -1,8 +1,10 @@
 import { corruptStoredRowContent, corruptStoredRowWhere } from './wireErrorTriage.js';
-import { resumePolicyBlockContent, resumePolicyBlockFromError } from './resumeRefusalCopy.js';
-export function decideFailureNote(err) {
+import { parkedResumeStartupContent, parkedResumeStartupFromError, resumePolicyBlockContent, resumePolicyBlockFromError, } from './resumeRefusalCopy.js';
+export function decideFailureNote(err, decision) {
     const where = corruptStoredRowWhere(err);
     const fold = resumePolicyBlockFromError(err);
+    const startup = parkedResumeStartupFromError(err, decision);
     return ((where === undefined ? '' : ` — ${corruptStoredRowContent(where)}`) +
-        (fold === null ? '' : ` — ${resumePolicyBlockContent(fold)}`));
+        (fold === null ? '' : ` — ${resumePolicyBlockContent(fold)}`) +
+        (startup === null ? '' : ` — ${parkedResumeStartupContent(startup)}`));
 }

package/dist/detachWire.d.ts

@@ -26,6 +26,7 @@ export declare function resolveHeadlessDetach(baseUrl: string, env?: EnvLike, op
     timeoutMs?: number;
 }): Promise<DetachResolution>;
 export declare const DETACH_DURABLE_OFF_400_ANCHOR = "x-detach-on-disconnect requires a durable run";
+export declare function isDetachDurableOff400(err: unknown): boolean;
 export declare function detachDurableOffHint(err: unknown): string | null;
 export interface DetachCancelArm {
     baseUrl: string;

package/dist/detachWire.js

@@ -57,14 +57,22 @@ export async function resolveHeadlessDetach(baseUrl, env = hostEnv(), opts) {
     return { on: true, reason: 'default-on' };
 }
 export const DETACH_DURABLE_OFF_400_ANCHOR = 'x-detach-on-disconnect requires a durable run';
+export function isDetachDurableOff400(err) {
+    try {
+        const e = err;
+        if (e?.status !== 400)
+            return false;
+        const msg = e?.message;
+        return typeof msg === 'string' && msg.includes(DETACH_DURABLE_OFF_400_ANCHOR);
+    }
+    catch {
+        return false;
+    }
+}
 export function detachDurableOffHint(err) {
     if (!isDetachArmed())
         return null;
-    const e = err;
-    if (e?.status !== 400)
-        return null;
-    const msg = typeof e?.message === 'string' ? e.message : '';
-    if (!msg.includes(DETACH_DURABLE_OFF_400_ANCHOR))
+    if (!isDetachDurableOff400(err))
         return null;
     return 'engine has durable runs disabled — detach-on-disconnect unavailable; interrupted turns will abort (SEMA_HEADLESS_DETACH=false to silence)';
 }