@sema-agent/client-core 0.89.0 → 0.91.0

package/dist/hitl/toolApprovalWire.js

@@ -10,6 +10,7 @@ import { isRuleStoreUnreadableKind } from '../gateVocabulary.js';
 import { isApprovalMandateWord } from '../gateVocabulary.js';
 import { denyAttributionRefusalFromError } from '../wireRefusalCopy.js';
 import { decideFailureNote } from '../decideFailureNote.js';
+import { refusalSaysStillPending } from '../engineErrorCodes.js';
 import { readDecideReceipt } from '../decideReceipt.js';
 import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS, ASK_ORIGINS, PERSISTED_RULE_MANDATES, } from '@sema-agent/sdk';
 export function isFsApprovalGate(gate) {
@@ -190,6 +191,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
     const callKey = approvalCallKey(gatedCallId, taskId);
     const ruleOffersReadOnly = readRuleOfferSupply(pending.ruleOffers, pending.ruleSuggestions);
     const durableProbeCause = pending.riskDescriptor?.probeCause;
+    const durableProbeReason = readProbeReason(pending.riskDescriptor);
     const durableShadowedRule = pending.riskDescriptor?.shadowedRule;
     const durableRuleOffersAbsence = pending.ruleOffersAbsence;
     const durableRuleStoreUnreadable = readRuleStoreUnreadable(pending.ruleStoreUnreadable);
@@ -215,6 +217,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         ...(pending.hasBidiControls === true ? { hasBidiControls: true } : {}),
         ...(ruleOffersReadOnly !== undefined ? { ruleOffersReadOnly } : {}),
         ...(isWireRecordCarrier(durableProbeCause) ? { probeCause: durableProbeCause } : {}),
+        ...(durableProbeReason !== undefined ? { probeReason: durableProbeReason } : {}),
         ...(durableRuleStoreUnreadable !== undefined
             ? { ruleStoreUnreadable: durableRuleStoreUnreadable }
             : {}),
@@ -279,6 +282,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                 catch (e) {
                     const currentPending = readDecideCurrentPending(e);
                     const wireCode = readWireErrorCode(e);
+                    const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
                     const safetyCode = e instanceof HitlSafetyError ? e.code : undefined;
                     return {
                         kind: 'failed',
@@ -288,6 +292,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                         ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
                         ...(currentPending !== undefined ? { currentPending } : {}),
                         ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
+                        ...(wireRetriable ? { retriable: true } : {}),
                         ...(safetyCode !== undefined ? { safetyCode } : {}),
                     };
                 }
@@ -335,6 +340,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                 catch (e) {
                     const currentPending = readDecideCurrentPending(e);
                     const wireCode = readWireErrorCode(e);
+                    const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
                     const safetyCode = e instanceof HitlSafetyError ? e.code : undefined;
                     const attributionRefusal = denyAttributionRefusalFromError(e, lastSendCarriedAttribution);
                     return {
@@ -345,6 +351,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                         ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
                         ...(currentPending !== undefined ? { currentPending } : {}),
                         ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
+                        ...(wireRetriable ? { retriable: true } : {}),
                         ...(safetyCode !== undefined ? { safetyCode } : {}),
                         ...(attributionRefusal !== null ? { denyAttributionRefusal: attributionRefusal } : {}),
                     };
@@ -393,6 +400,7 @@ export const TOOL_APPROVAL_FRAME_KEYS_MIRROR = [
     'parked',
     'persistedRuleShadowed',
     'probeCause',
+    'probeReason',
     'ruleEvidence',
     'requiresRealApproval',
     'expiresInMs',
@@ -644,6 +652,17 @@ function pathFromGateMessage(message) {
         return undefined;
     return body.slice(0, close);
 }
+function readProbeReason(v) {
+    try {
+        if (typeof v !== 'object' || v === null || !Object.hasOwn(v, 'probeReason'))
+            return undefined;
+        const raw = v.probeReason;
+        return typeof raw === 'string' && raw.trim() !== '' ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function isNonNegativeFinite(v) {
     return typeof v === 'number' && Number.isFinite(v) && v >= 0;
 }
@@ -887,6 +906,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
             ? { persistedRuleShadowed: frame.persistedRuleShadowed }
             : {}),
         ...(isWireRecordCarrier(frame.probeCause) ? { probeCause: frame.probeCause } : {}),
+        ...((r) => (r !== undefined ? { probeReason: r } : {}))(readProbeReason(frame)),
         ...(isWireRecordCarrier(frame.ruleEvidence) ? { ruleEvidence: frame.ruleEvidence } : {}),
         ...(frame.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
         ...(hasOwnStrictTrue(frame, 'mandated') ? { mandated: true } : {}),

package/dist/hookMatcherVerdict.d.ts

@@ -0,0 +1,29 @@
+export type HookMatcherUnjudgedReason = 'event_out_of_scope' | 'not_a_string' | 'oversize' | 'invalid_pattern' | 'pattern_unsupported' | 'over_budget';
+export type HookMatcherVerdict = {
+    readonly kind: 'matchesAll';
+} | {
+    readonly kind: 'accepted';
+    readonly reading: 'names';
+    readonly names: readonly string[];
+    readonly aliases: readonly {
+        readonly alias: string;
+        readonly canonical: string;
+    }[];
+} | {
+    readonly kind: 'accepted';
+    readonly reading: 'pattern';
+    readonly aliases: readonly {
+        readonly alias: string;
+        readonly canonical: string;
+    }[];
+} | {
+    readonly kind: 'refused';
+    readonly reason: 'alias_without_canonical';
+    readonly reading: 'names' | 'pattern';
+    readonly alias: string;
+    readonly canonical: string;
+} | {
+    readonly kind: 'unjudged';
+    readonly reason: HookMatcherUnjudgedReason;
+};
+export declare function hookMatcherVerdict(event: string, matcher: unknown): HookMatcherVerdict;

package/dist/hookMatcherVerdict.js

@@ -0,0 +1,265 @@
+import { HOOK_TOOL_ALIASES } from './hookToolAliases.js';
+const TOOL_NAME_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'PostToolUseFailure']);
+const MATCHER_MAX_CHARS = 8192;
+const PATTERN_WORK_BUDGET = 10_000_000;
+const PATTERN_MAX_DEPTH = 32;
+const COUNTED_REPEAT_MAX = 1000;
+function unjudged(reason) {
+    return Object.freeze({ kind: 'unjudged', reason });
+}
+function refused(reading, p) {
+    return Object.freeze({ kind: 'refused', reason: 'alias_without_canonical', reading, alias: p.alias, canonical: p.canonical });
+}
+function aliasPairs() {
+    return Object.entries(HOOK_TOOL_ALIASES).map(([alias, canonical]) => ({ alias, canonical }));
+}
+function literalNames(matcher) {
+    const names = [];
+    let first = -1;
+    let last = -1;
+    for (let i = 0; i <= matcher.length; i++) {
+        const c = i < matcher.length ? matcher.charCodeAt(i) : 0x7c;
+        if (c === 0x7c || c === 0x2c) {
+            if (first !== -1)
+                names.push(matcher.slice(first, last + 1));
+            first = -1;
+            last = -1;
+            continue;
+        }
+        if (c === 0x20)
+            continue;
+        const nameChar = (c >= 0x30 && c <= 0x39) || (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a) || c === 0x5f || c === 0x2d;
+        if (!nameChar)
+            return undefined;
+        if (first === -1)
+            first = i;
+        last = i;
+    }
+    return names;
+}
+const UNSUPPORTED = Symbol('unsupported');
+const SINGLE_CHAR_ESCAPES = 'dDwWsStnrfv^$\\.*+?()[]{}|/-';
+function patternBound(src, n) {
+    let i = 0;
+    let depth = 0;
+    const fail = () => {
+        throw UNSUPPORTED;
+    };
+    const quantifier = () => {
+        const c = src[i];
+        let lo;
+        let hi;
+        if (c === '*') {
+            lo = 0;
+            hi = Infinity;
+            i++;
+        }
+        else if (c === '+') {
+            lo = 1;
+            hi = Infinity;
+            i++;
+        }
+        else if (c === '?') {
+            lo = 0;
+            hi = 1;
+            i++;
+        }
+        else if (c === '{') {
+            const q = /^\{(\d{1,4})(?:(,)(\d{0,4}))?\}/.exec(src.slice(i, i + 12));
+            if (q === null)
+                return fail();
+            lo = Number(q[1]);
+            hi = q[2] === undefined ? lo : q[3] === '' || q[3] === undefined ? Infinity : Number(q[3]);
+            if (lo > COUNTED_REPEAT_MAX || (hi !== Infinity && hi > COUNTED_REPEAT_MAX) || hi < lo)
+                fail();
+            i += q[0].length;
+        }
+        else
+            return undefined;
+        if (src[i] === '?')
+            i++;
+        return { lo, hi };
+    };
+    const term = () => {
+        const c = src[i];
+        if (c === '^' || c === '$') {
+            i++;
+            if (quantifier() !== undefined)
+                fail();
+            return [1, 1];
+        }
+        if (c === '\\' && (src[i + 1] === 'b' || src[i + 1] === 'B')) {
+            i += 2;
+            if (quantifier() !== undefined)
+                fail();
+            return [1, 1];
+        }
+        let paths = 1;
+        let steps = 1;
+        let single = true;
+        if (c === '(') {
+            i++;
+            if (src[i] === '?') {
+                if (src[i + 1] === ':')
+                    i += 2;
+                else {
+                    const named = /^\?<([A-Za-z_$][A-Za-z0-9_$]*)>/.exec(src.slice(i, i + 80));
+                    if (named === null)
+                        fail();
+                    else
+                        i += named[0].length;
+                }
+            }
+            if (++depth > PATTERN_MAX_DEPTH)
+                fail();
+            [paths, steps] = disjunction();
+            if (src[i] !== ')')
+                fail();
+            i++;
+            depth--;
+            single = false;
+        }
+        else if (c === '[') {
+            i++;
+            if (src[i] === '^')
+                i++;
+            for (;;) {
+                if (i >= src.length)
+                    fail();
+                const d = src[i];
+                if (d === ']') {
+                    i++;
+                    break;
+                }
+                i += d === '\\' ? 2 : 1;
+            }
+        }
+        else if (c === '.')
+            i++;
+        else if (c === '\\') {
+            const e = src[i + 1];
+            if (e === undefined || !SINGLE_CHAR_ESCAPES.includes(e))
+                fail();
+            i += 2;
+        }
+        else if (c === undefined || '*+?{}]|)'.includes(c))
+            fail();
+        else
+            i++;
+        const q = quantifier();
+        if (q === undefined)
+            return [paths, steps];
+        if (single) {
+            if (q.lo > n)
+                return [1, n + 1];
+            const top = Math.min(q.hi, n);
+            return [top - q.lo + 1, top + 1];
+        }
+        const hiEff = Math.min(q.hi, Math.max(q.lo, n + 1));
+        if (q.lo > hiEff)
+            return [1, 1];
+        let sum = 0;
+        for (let k = q.lo; k <= hiEff; k++) {
+            sum += paths ** k;
+            if (sum === Infinity)
+                break;
+        }
+        return [sum, hiEff * steps + 1];
+    };
+    const alternative = () => {
+        let paths = 1;
+        let steps = 0;
+        while (i < src.length && src[i] !== '|' && src[i] !== ')') {
+            const [p, s] = term();
+            paths *= p;
+            steps += s;
+        }
+        return [paths, steps];
+    };
+    const disjunction = () => {
+        let [paths, steps] = alternative();
+        while (src[i] === '|') {
+            i++;
+            const [p, s] = alternative();
+            paths += p;
+            steps = Math.max(steps, s);
+        }
+        return [paths, steps];
+    };
+    try {
+        const r = disjunction();
+        if (i !== src.length)
+            fail();
+        return r;
+    }
+    catch (e) {
+        if (e === UNSUPPORTED)
+            return undefined;
+        throw e;
+    }
+}
+export function hookMatcherVerdict(event, matcher) {
+    if (typeof event !== 'string' || !TOOL_NAME_MATCHER_EVENTS.has(event))
+        return unjudged('event_out_of_scope');
+    if (matcher === undefined)
+        return Object.freeze({ kind: 'matchesAll' });
+    if (typeof matcher !== 'string')
+        return unjudged('not_a_string');
+    if (matcher.length > MATCHER_MAX_CHARS)
+        return unjudged('oversize');
+    if (matcher === '' || matcher === '*')
+        return Object.freeze({ kind: 'matchesAll' });
+    const pairs = aliasPairs();
+    const names = literalNames(matcher);
+    if (names !== undefined) {
+        const dead = pairs.find((p) => names.includes(p.alias) && !names.includes(p.canonical));
+        if (dead !== undefined)
+            return refused('names', dead);
+        return Object.freeze({
+            kind: 'accepted',
+            reading: 'names',
+            names: Object.freeze([...names]),
+            aliases: Object.freeze(pairs.filter((p) => names.includes(p.alias)).map((p) => Object.freeze({ ...p }))),
+        });
+    }
+    const src = `^(?:${matcher})$`;
+    let re;
+    try {
+        re = new RegExp(src);
+    }
+    catch {
+        return unjudged('invalid_pattern');
+    }
+    const subjects = pairs.flatMap((p) => [p.alias, p.canonical]);
+    const n = subjects.reduce((a, s) => Math.max(a, s.length), 0);
+    const bound = patternBound(src, n);
+    if (bound === undefined)
+        return unjudged('pattern_unsupported');
+    if (bound[0] * bound[1] * (n + 1) * subjects.length > PATTERN_WORK_BUDGET)
+        return unjudged('over_budget');
+    const selects = (name) => {
+        if (matcher === name)
+            return true;
+        try {
+            return re.test(name);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const selected = [];
+    for (const p of pairs) {
+        const a = selects(p.alias);
+        if (a === undefined)
+            return unjudged('invalid_pattern');
+        if (!a)
+            continue;
+        const c = selects(p.canonical);
+        if (c === undefined)
+            return unjudged('invalid_pattern');
+        if (!c)
+            return refused('pattern', p);
+        selected.push(p);
+    }
+    return Object.freeze({ kind: 'accepted', reading: 'pattern', aliases: Object.freeze(selected.map((p) => Object.freeze({ ...p }))) });
+}

package/dist/hookToolAliases.d.ts

@@ -0,0 +1,3 @@
+export declare const HOOK_TOOL_ALIASES: Readonly<Record<string, string>>;
+export declare function hookToolAliasesOf(): Readonly<Record<string, string>>;
+export declare function canonicalHookToolName(name: string): string;

package/dist/hookToolAliases.js

@@ -0,0 +1,10 @@
+import { CORE_HOOK_TOOL_ALIASES } from './generated/engineFactTables.js';
+export const HOOK_TOOL_ALIASES = CORE_HOOK_TOOL_ALIASES;
+export function hookToolAliasesOf() {
+    return HOOK_TOOL_ALIASES;
+}
+export function canonicalHookToolName(name) {
+    if (typeof name !== 'string')
+        return name;
+    return Object.hasOwn(HOOK_TOOL_ALIASES, name) ? (HOOK_TOOL_ALIASES[name] ?? name) : name;
+}

package/dist/humanTurn.d.ts

@@ -0,0 +1,91 @@
+import type { ImageInput } from './imagesWireCaps.js';
+import type { ImageVision } from './liveModelCatalog.js';
+import { type UserAttachmentDescriptor } from './userAttachmentEnvelope.js';
+export interface HumanTurnRider {
+    readonly uuid: string;
+    readonly role: 'image_meta' | 'attachment' | 'skill_body' | (string & {});
+    readonly textIncluded: boolean;
+}
+export interface HumanTurnMissing {
+    readonly kind: 'rider_text' | 'image' | 'attachment_ref' | 'non_text';
+    readonly ref?: string;
+    readonly reason: 'not_persisted' | 'not_found' | 'non_text_filtered' | 'projection_failed';
+}
+export interface HumanTurnAttachment {
+    readonly uuid: string;
+    readonly descriptor: Exclude<UserAttachmentDescriptor, {
+        kind: 'image';
+    }> | Omit<Extract<UserAttachmentDescriptor, {
+        kind: 'image';
+    }>, 'delivery'>;
+    readonly pixels?: {
+        readonly data: string;
+        readonly mimeType: string;
+    };
+}
+export interface HumanTurnItem {
+    readonly uuid: string;
+    readonly text: string;
+    readonly images?: readonly ImageInput[];
+    readonly attachments?: readonly HumanTurnAttachment[];
+    readonly attachmentIds?: readonly string[];
+    readonly riders?: readonly HumanTurnRider[];
+    readonly missing?: readonly HumanTurnMissing[];
+}
+export interface HumanTurnCaps {
+    readonly vision?: ImageVision;
+}
+export interface HumanTurnInput {
+    readonly items: readonly HumanTurnItem[];
+    readonly lane: 'objective' | 'steer';
+    readonly caps: HumanTurnCaps;
+    readonly otherBodyBytes?: number;
+}
+type EncoderShortfall = 'body_budget' | 'steer_admission' | 'vision_no' | 'vision_unknown' | 'image_too_large' | 'seat_count' | 'seat_total' | 'lane_has_no_image_seat' | 'lane_has_no_attachment_id_seat';
+export interface HumanTurnSharePart {
+    readonly kind: 'text' | 'image' | 'attachment_ref' | 'attachment_id' | 'rider_text' | 'non_text';
+    readonly ref?: string | number;
+    readonly status: 'full' | 'none';
+    readonly why?: EncoderShortfall | 'text_not_included' | HumanTurnMissing['reason'];
+}
+export interface HumanTurnShare {
+    readonly uuid: string;
+    readonly riderUuids: readonly string[];
+    readonly level: 'full' | 'partial' | 'none';
+    readonly parts: readonly HumanTurnSharePart[];
+}
+export interface HumanTurnDegraded {
+    readonly uuid: string;
+    readonly kind: HumanTurnSharePart['kind'];
+    readonly ref?: string | number;
+    readonly why: EncoderShortfall;
+}
+export type HumanTurnEncoding = {
+    readonly ok: true;
+    readonly lane: 'objective';
+    readonly text: string;
+    readonly images: readonly ImageInput[];
+    readonly attachmentIds: readonly string[];
+    readonly shares: readonly HumanTurnShare[];
+    readonly degraded: readonly HumanTurnDegraded[];
+} | {
+    readonly ok: true;
+    readonly lane: 'steer';
+    readonly text: string;
+    readonly shares: readonly HumanTurnShare[];
+    readonly degraded: readonly HumanTurnDegraded[];
+} | {
+    readonly ok: false;
+    readonly reason: 'steer_hold';
+    readonly why: 'no_text' | 'reminder_tag' | 'control_char' | 'too_long';
+} | {
+    readonly ok: false;
+    readonly reason: 'empty' | 'malformed_input' | 'malformed_item' | 'duplicate_uuid' | 'rider_collides_primary' | 'oversize';
+};
+export interface HumanTurnDelivered {
+    readonly full: readonly string[];
+    readonly partial: readonly string[];
+}
+export declare function encodeHumanTurn(input: HumanTurnInput): HumanTurnEncoding;
+export declare function deliveredUuidsOf(encoding: HumanTurnEncoding): HumanTurnDelivered;
+export {};