@sema-agent/client-core 0.82.1 → 0.82.3

package/dist/cloudConfigWireCaps.js

@@ -114,19 +114,153 @@ export function cloudSkillsToSpecs(manifestSkills, resolveBody) {
     }
     return specs;
 }
-export function cloudModelsToDoc(models) {
+const REGISTRY_ENTRY_ANNOTATION_KEYS = ['origin', 'overridesTeam'];
+function withoutRegistryAnnotations(e) {
+    const r = asRec(e);
+    if (!r || !REGISTRY_ENTRY_ANNOTATION_KEYS.some((k) => Object.hasOwn(r, k)))
+        return e;
+    const out = {};
+    for (const [k, v] of Object.entries(r)) {
+        if (REGISTRY_ENTRY_ANNOTATION_KEYS.includes(k))
+            continue;
+        setOwn(out, k, v);
+    }
+    return out;
+}
+const TIER_WORDS = Object.freeze(['ultra', 'max', 'pro', 'flash', 'lite']);
+const TIER_GROUP_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+const setOwn = (o, k, v) => {
+    Object.defineProperty(o, k, { value: v, enumerable: true, writable: true, configurable: true });
+};
+function modelsDocOf(models, opts) {
     const m = asRec(models);
     if (!m || !Array.isArray(m.models))
-        return null;
+        return { doc: null, issues: [] };
     const entries = m.models.filter((e) => {
         const r = asRec(e);
         return !!r && !!asStr(r.name) && !!asStr(r.id);
     });
-    return {
-        models: entries,
-        ...(asRec(m.roles) ? { roles: m.roles } : {}),
-        ...(Array.isArray(m.atModelAllowlist) ? { atModelAllowlist: m.atModelAllowlist } : {}),
+    const stripped = entries.map(withoutRegistryAnnotations);
+    const allNames = new Set(entries.map((e) => e.name));
+    const rawNames = new Set(m.models.map((e) => asStr(asRec(e)?.name)).filter((n) => !!n));
+    const accept = typeof opts?.entryAccepted === 'function' ? opts.entryAccepted : undefined;
+    const acceptedName = (e) => {
+        try {
+            const copy = JSON.parse(JSON.stringify(e));
+            return typeof copy === 'object' && copy !== null && accept(copy) === true;
+        }
+        catch {
+            return false;
+        }
     };
+    const acceptedFlags = accept ? stripped.map(acceptedName) : undefined;
+    const names = acceptedFlags ? new Set(stripped.filter((_, i) => acceptedFlags[i]).map((e) => e.name)) : allNames;
+    const issues = [];
+    const drop = (i) => {
+        issues.push({ ...i, outcome: 'dropped' });
+    };
+    const refOf = (v) => (typeof v === 'string' && v !== '' ? { target: v } : {});
+    const reasonOf = (v) => typeof v === 'string' && v !== '' ? (rawNames.has(v) ? 'rejected' : 'dangling') : 'unreadable';
+    let written = stripped;
+    if (acceptedFlags && stripped.length > 0) {
+        const anyAccepted = acceptedFlags.some((f) => f);
+        stripped.forEach((e, i) => {
+            if (!acceptedFlags[i])
+                issues.push({ key: 'models', target: e.name, reason: 'rejected', outcome: anyAccepted ? 'dropped' : 'kept' });
+        });
+        if (anyAccepted)
+            written = stripped.filter((_, i) => acceptedFlags[i]);
+    }
+    const doc = { models: written };
+    if (accept && Object.hasOwn(m, 'default')) {
+        const d = m.default;
+        if (typeof d === 'string' && names.has(d))
+            doc.default = d;
+        else
+            drop({ key: 'default', ...refOf(d), reason: reasonOf(d) });
+    }
+    const roles = asRec(m.roles);
+    if (roles) {
+        const kept = {};
+        for (const [role, t] of Object.entries(roles)) {
+            const tr = asRec(t);
+            const model = tr && Object.hasOwn(tr, 'model') ? tr.model : undefined;
+            if (typeof model === 'string' && !names.has(model)) {
+                drop({ key: 'roles', at: role, ...refOf(model), reason: reasonOf(model) });
+                continue;
+            }
+            setOwn(kept, role, t);
+        }
+        doc.roles = kept;
+    }
+    if (Array.isArray(m.atModelAllowlist)) {
+        const src = m.atModelAllowlist;
+        const keep = src.filter((n) => typeof n === 'string' && names.has(n));
+        if (keep.length === 0 && src.length > 0) {
+            doc.atModelAllowlist = src;
+            for (const n of src)
+                issues.push({ key: 'atModelAllowlist', ...refOf(n), reason: reasonOf(n), outcome: 'kept' });
+        }
+        else {
+            for (const n of src)
+                if (!(typeof n === 'string' && names.has(n)))
+                    drop({ key: 'atModelAllowlist', ...refOf(n), reason: reasonOf(n) });
+            doc.atModelAllowlist = keep;
+        }
+    }
+    let groupNames;
+    const rawGroupNames = new Set((Array.isArray(m.tierGroups) ? m.tierGroups : []).map((g) => asStr(asRec(g)?.name)).filter((n) => !!n));
+    if (accept && Object.hasOwn(m, 'tierGroups')) {
+        if (!Array.isArray(m.tierGroups)) {
+            drop({ key: 'tierGroups', reason: 'unreadable' });
+        }
+        else {
+            const groups = [];
+            groupNames = new Set();
+            for (const raw of m.tierGroups) {
+                const g = asRec(raw);
+                const name = g ? asStr(g.name) : undefined;
+                if (!g || !name || !TIER_GROUP_NAME.test(name)) {
+                    drop({ key: 'tierGroups', ...(name ? { at: name } : {}), reason: 'unreadable' });
+                    continue;
+                }
+                if (groupNames.has(name)) {
+                    drop({ key: 'tierGroups', at: name, reason: 'duplicate' });
+                    continue;
+                }
+                groupNames.add(name);
+                const tiers = {};
+                if (Object.hasOwn(g, 'tiers')) {
+                    const t = asRec(g.tiers);
+                    if (!t)
+                        drop({ key: 'tierGroups', at: `${name}.tiers`, reason: 'unreadable' });
+                    else {
+                        for (const [tier, model] of Object.entries(t)) {
+                            if (!TIER_WORDS.includes(tier))
+                                drop({ key: 'tierGroups', at: `${name}.${tier}`, ...refOf(model), reason: 'unsupported' });
+                            else if (typeof model === 'string' && names.has(model))
+                                setOwn(tiers, tier, model);
+                            else
+                                drop({ key: 'tierGroups', at: `${name}.${tier}`, ...refOf(model), reason: reasonOf(model) });
+                        }
+                    }
+                }
+                groups.push({ name, tiers, ...(typeof g.notes === 'string' ? { notes: g.notes } : {}) });
+            }
+            doc.tierGroups = groups;
+        }
+    }
+    if (accept && Object.hasOwn(m, 'activeTierGroup')) {
+        const a = m.activeTierGroup;
+        if (typeof a === 'string' && groupNames?.has(a))
+            doc.activeTierGroup = a;
+        else
+            drop({ key: 'activeTierGroup', ...refOf(a), reason: typeof a === 'string' && a !== '' ? (rawGroupNames.has(a) ? 'rejected' : 'dangling') : 'unreadable' });
+    }
+    return { doc, issues };
+}
+export function cloudModelsToDoc(models, opts) {
+    return modelsDocOf(models, opts).doc;
 }
 export function cloudModelsDropped(models) {
     const m = asRec(models);
@@ -184,7 +318,136 @@ export function cloudRosterNames(rostersValue) {
         .map((e) => asStr(asRec(e)?.name))
         .filter((n) => !!n);
 }
-export function projectEffectiveBody(body, skillBodies, env, rostersValue) {
+const BUDGET_NUMBER_KEYS = ['maxBudgetUsd', 'tpmLimit', 'rpmLimit', 'maxParallelRequests', 'maxRunCostUsd', 'maxIterations'];
+const BUDGET_STRING_KEYS = ['mode', 'budgetDuration', 'enforcement'];
+const PER_MODEL_NUMBER_KEYS = ['maxBudgetUsd', 'tpmLimit', 'rpmLimit'];
+const _budgetKeysCovered = true;
+const _budgetKeysReal = true;
+const _perModelKeysCovered = true;
+void _budgetKeysCovered;
+void _budgetKeysReal;
+void _perModelKeysCovered;
+const isFiniteNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const ownOf = (o, k) => (Object.hasOwn(o, k) ? o[k] : undefined);
+const inList = (list, k) => list.includes(k);
+const viewModeOf = (b) => (!Object.hasOwn(b, 'previewOf') ? 'self' : asStr(b.previewOf) ? 'preview' : 'unknown');
+const nullReadingOf = (mode) => mode === 'self' ? { kind: 'not-configured' } : mode === 'preview' ? { kind: 'redacted' } : { kind: 'unknown' };
+function effectiveWarningsOf(b) {
+    const raw = ownOf(b, 'warnings');
+    if (!Array.isArray(raw))
+        return { kind: 'unknown' };
+    const warnings = [];
+    let unreadable = 0;
+    for (const row of raw) {
+        const w = asRec(row);
+        const kind = w ? asStr(ownOf(w, 'kind')) : undefined;
+        if (!w || !kind) {
+            unreadable += 1;
+            continue;
+        }
+        const out = { kind };
+        const domain = asStr(ownOf(w, 'domain'));
+        if (domain)
+            out.domain = domain;
+        for (const k of ['droppedNames', 'keys']) {
+            const xs = ownOf(w, k);
+            if (Array.isArray(xs)) {
+                const names = xs.filter((x) => typeof x === 'string' && x.length > 0);
+                if (names.length > 0)
+                    out[k] = names;
+            }
+        }
+        for (const k of ['path', 'file', 'why']) {
+            const s = asStr(ownOf(w, k));
+            if (s)
+                out[k] = s;
+        }
+        const tf = ownOf(w, 'truncatedFrom');
+        if (isFiniteNum(tf))
+            out.truncatedFrom = tf;
+        warnings.push(out);
+    }
+    return { kind: 'reported', warnings, unreadable };
+}
+function budgetOf(b, mode) {
+    if (!Object.hasOwn(b, 'budget'))
+        return { kind: 'unknown' };
+    const v = b.budget;
+    if (v === null)
+        return nullReadingOf(mode);
+    const r = asRec(v);
+    if (!r)
+        return { kind: 'unknown' };
+    const limits = {};
+    const uninterpreted = [];
+    for (const [k, val] of Object.entries(r)) {
+        if (inList(BUDGET_NUMBER_KEYS, k)) {
+            if (isFiniteNum(val))
+                limits[k] = val;
+            else
+                uninterpreted.push(k);
+        }
+        else if (inList(BUDGET_STRING_KEYS, k)) {
+            const s = asStr(val);
+            if (s)
+                limits[k] = s;
+            else
+                uninterpreted.push(k);
+        }
+        else if (k === 'perModel') {
+            const pm = asRec(val);
+            if (!pm) {
+                uninterpreted.push(k);
+                continue;
+            }
+            const perModel = {};
+            for (const [model, entry] of Object.entries(pm)) {
+                const e = asRec(entry);
+                if (!e) {
+                    uninterpreted.push(`perModel.${model}`);
+                    continue;
+                }
+                const one = {};
+                let unread = 0;
+                for (const [k2, v2] of Object.entries(e)) {
+                    if (inList(PER_MODEL_NUMBER_KEYS, k2) && isFiniteNum(v2))
+                        one[k2] = v2;
+                    else {
+                        uninterpreted.push(`perModel.${model}.${k2}`);
+                        unread += 1;
+                    }
+                }
+                if (Object.keys(one).length > 0 || unread === 0)
+                    setOwn(perModel, model, one);
+            }
+            limits.perModel = perModel;
+        }
+        else {
+            uninterpreted.push(k);
+        }
+    }
+    return { kind: 'configured', limits, uninterpretedKeys: uninterpreted };
+}
+function runtimeCapsOf(b, mode) {
+    if (!Object.hasOwn(b, 'runtimeCaps'))
+        return { kind: 'unknown' };
+    const v = b.runtimeCaps;
+    if (v === null)
+        return nullReadingOf(mode);
+    const r = asRec(v);
+    if (!r)
+        return { kind: 'unknown' };
+    const caps = {};
+    const uninterpreted = [];
+    for (const [k, val] of Object.entries(r)) {
+        if (typeof val === 'boolean')
+            setOwn(caps, k, val);
+        else
+            uninterpreted.push(k);
+    }
+    return { kind: 'configured', caps, uninterpretedKeys: uninterpreted };
+}
+export function projectEffectiveBody(body, skillBodies, env, rostersValue, opts) {
     const b = asRec(body) ?? {};
     const config = asRec(b.config) ?? {};
     const mcpDomain = asRec(config.mcp);
@@ -202,7 +465,8 @@ export function projectEffectiveBody(body, skillBodies, env, rostersValue) {
         return name && hash && skillBodies[hash] === undefined ? name : undefined;
     })
         .filter((n) => !!n);
-    const modelsDoc = cloudModelsToDoc(config.models);
+    const { doc: modelsDoc, issues: modelRefIssues } = modelsDocOf(config.models, opts);
+    const view = viewModeOf(b);
     return {
         mcp,
         skills,
@@ -215,5 +479,138 @@ export function projectEffectiveBody(body, skillBodies, env, rostersValue) {
         droppedMcpServers,
         droppedModels: cloudModelsDropped(config.models),
         execution: cloudExecutionToPolicy(config.execution),
+        effectiveWarnings: effectiveWarningsOf(b),
+        budget: budgetOf(b, view),
+        runtimeCaps: runtimeCapsOf(b, view),
+        modelRefIssues,
     };
 }
+const quoted = (s, fallback) => (s === undefined ? fallback : `the "${s}" settings`);
+const listOf = (xs, truncatedFrom) => xs === undefined ? '' : `: ${xs.join(', ')}${truncatedFrom === undefined ? '' : ` (${truncatedFrom} in total)`}`;
+function warningNotice(w) {
+    const where = quoted(w.domain, 'the configuration');
+    switch (w.kind) {
+        case 'hosts-grandfathered':
+            return { level: 'warn', text: `cloud config warning: host entries exceeding the current limits were skipped by the registry${listOf(w.droppedNames, w.truncatedFrom)}` };
+        case 'domain-defaulted':
+            return { level: 'warn', text: `cloud config warning: ${where} could not be read by the registry and were served as defaults — what is configured there is not in effect` };
+        case 'entry-dropped':
+            return { level: 'warn', text: `cloud config warning: an entry in ${where} could not be read by the registry and was left out${w.path === undefined ? '' : ` (${w.path})`}` };
+        case 'unknown-keys-dropped':
+            return { level: 'warn', text: `cloud config warning: the registry dropped unrecognised keys from ${where}${listOf(w.keys, w.truncatedFrom)}` };
+        case 'unknown-keys-carried':
+            return { level: 'warn', text: `cloud config warning: ${where} carry keys the registry does not recognise, passed on as written (check the spelling)${listOf(w.keys, w.truncatedFrom)}` };
+        case 'legacy-governance-lifted':
+            return { level: 'info', text: `cloud config note: ${where} were taken from their older location${listOf(w.keys, undefined)}` };
+        case 'unread-config-file':
+            return { level: 'warn', text: `cloud config warning: a configuration file was not read by the registry${w.file === undefined ? '' : ` (${w.file}${w.why === undefined ? '' : `: ${w.why}`})`}` };
+        default:
+            return { level: 'warn', text: `cloud config warning: the registry reported "${w.kind}"${w.domain === undefined ? '' : ` for ${where}`} — this client does not recognise that warning, so the served configuration may be degraded` };
+    }
+}
+function droppedRefNotice(d) {
+    const t = d.target;
+    const notServed = d.reason === 'rejected'
+        ? 'is in the catalog, but its entry is one the local engine cannot use (incomplete or invalid settings)'
+        : 'is not in the model catalog served to you';
+    switch (d.key) {
+        case 'models':
+            return { level: 'warn', text: `cloud config: ${t === undefined ? 'a model entry' : `model "${t}"`} is in the catalog, but its entry is one the local engine cannot use (incomplete or invalid settings) — it was left out of the local catalog` };
+        case 'default':
+            return { level: 'warn', text: `cloud config: ${t === undefined ? 'the default model setting could not be read' : `the default model "${t}" ${notServed}`}, so it was left out — the local engine picks its default from roles and tiers instead` };
+        case 'roles':
+            return { level: 'warn', text: `cloud config: role "${d.at ?? ''}" ${t === undefined ? 'names no readable model' : `points at model "${t}", which ${notServed}`} — the role was left out and falls back along the engine's role chain` };
+        case 'atModelAllowlist':
+            return { level: 'warn', text: `cloud config: ${t === undefined ? 'an unreadable @-mention allowlist entry' : `@-mention allowlist entry "${t}" ${notServed} and`} was left out` };
+        case 'tierGroups':
+            if (d.reason === 'duplicate')
+                return { level: 'warn', text: `cloud config: tier group "${d.at ?? ''}" appears more than once — only the first one is kept` };
+            if (d.reason === 'dangling' || d.reason === 'rejected')
+                return { level: 'warn', text: `cloud config: tier "${d.at ?? ''}" is bound to model "${t ?? ''}", which ${notServed} — that tier was left unbound` };
+            if (d.reason === 'unsupported')
+                return { level: 'warn', text: `cloud config: tier "${d.at ?? ''}" is not a tier the local engine reads (${TIER_WORDS.join(', ')}) — that binding was left out` };
+            return { level: 'warn', text: `cloud config: a tier group setting${d.at === undefined ? '' : ` ("${d.at}")`} could not be read and was left out` };
+        case 'activeTierGroup':
+            return { level: 'warn', text: `cloud config: ${t === undefined ? 'the active tier group setting could not be read' : `the active tier group "${t}" is not among the readable tier groups`} — no tier table is active on the local engine` };
+    }
+}
+function budgetNotice(r) {
+    switch (r.kind) {
+        case 'configured': {
+            const l = r.limits;
+            const parts = [];
+            for (const k of ['mode', 'maxBudgetUsd', 'budgetDuration', 'tpmLimit', 'rpmLimit', 'maxParallelRequests', 'maxRunCostUsd', 'maxIterations', 'enforcement']) {
+                if (l[k] !== undefined)
+                    parts.push(`${k} ${String(l[k])}`);
+            }
+            for (const [model, one] of Object.entries(l.perModel ?? {})) {
+                const inner = PER_MODEL_NUMBER_KEYS.filter((k) => one[k] !== undefined).map((k) => `${k} ${String(one[k])}`);
+                parts.push(`perModel ${model}: ${inner.length > 0 ? inner.join(', ') : 'no limits set'}`);
+            }
+            const extra = r.uninterpretedKeys.length > 0 ? `also carries ${r.uninterpretedKeys.join(', ')} (not shown by this client)` : '';
+            const body = parts.length > 0 ? parts.join(' · ') + (extra ? ` · ${extra}` : '') : extra ? `configured — ${extra}` : 'configured, with no limits set';
+            return { level: 'info', text: `cloud budget: ${body}` };
+        }
+        case 'not-configured':
+            return { level: 'info', text: "cloud budget: none set for you in the organisation's entitlement settings on this registry (pooled budgets and token quotas are separate readings)" };
+        case 'redacted':
+            return { level: 'info', text: 'cloud budget: withheld — this response previews another principal, and budget values are not shown in previews' };
+        case 'unknown':
+            return { level: 'info', text: 'cloud budget: not reported in a readable form by this registry — unknown, which is not the same as having no budget' };
+    }
+}
+function runtimeCapsNotice(r) {
+    switch (r.kind) {
+        case 'configured': {
+            const parts = Object.entries(r.caps).map(([k, v]) => `${k}=${String(v)}`);
+            const extra = r.uninterpretedKeys.length > 0 ? `also carries ${r.uninterpretedKeys.join(', ')} (not shown by this client)` : '';
+            const body = parts.length > 0 ? parts.join(', ') + (extra ? ` · ${extra}` : '') : extra ? `configured — ${extra}` : 'configured, with no caps set';
+            return { level: 'info', text: `cloud runtime caps: ${body}` };
+        }
+        case 'not-configured':
+            return { level: 'info', text: 'cloud runtime caps: none set for you on this registry — local controls decide' };
+        case 'redacted':
+            return { level: 'info', text: 'cloud runtime caps: withheld — this response previews another principal, and cap values are not shown in previews' };
+        case 'unknown':
+            return { level: 'info', text: 'cloud runtime caps: not reported in a readable form by this registry — unknown, which is not the same as having no caps' };
+    }
+}
+export function cloudEffectiveNotices(p) {
+    const out = [];
+    const w = p.effectiveWarnings;
+    if (w.kind === 'unknown') {
+        out.push({ level: 'info', text: 'cloud config: this registry does not report configuration degradation warnings — whether the served configuration was degraded is unknown' });
+    }
+    else {
+        for (const one of w.warnings)
+            out.push(warningNotice(one));
+        if (w.unreadable > 0) {
+            out.push({ level: 'warn', text: `cloud config warning: ${w.unreadable} warning ${w.unreadable === 1 ? 'entry' : 'entries'} from the registry could not be read by this client — the served configuration may be degraded` });
+        }
+    }
+    for (const d of p.modelRefIssues)
+        if (d.outcome === 'dropped')
+            out.push(droppedRefNotice(d));
+    const keptModels = p.modelRefIssues.filter((d) => d.outcome === 'kept' && d.key === 'models');
+    if (keptModels.length > 0) {
+        const named = keptModels.flatMap((d) => (d.target === undefined ? [] : [`"${d.target}"`]));
+        const shown = named.slice(0, 5).join(', ') + (named.length > 5 ? `, +${named.length - 5} more` : '');
+        out.push({
+            level: 'warn',
+            text: `cloud config: none of the model entries served to you${shown !== '' ? ` (${shown})` : ''} is one the local engine can use (incomplete or invalid settings) — ` +
+                'the catalog is kept as sent, and a locally started engine rejects the cloud model settings: at startup it uses its own environment catalog instead, and on a later refresh it keeps the previous configuration',
+        });
+    }
+    const keptAllowlist = p.modelRefIssues.filter((d) => d.outcome === 'kept' && d.key === 'atModelAllowlist');
+    if (keptAllowlist.length > 0) {
+        const names = keptAllowlist.flatMap((d) => (d.target === undefined ? [] : [`"${d.target}"`]));
+        out.push({
+            level: 'warn',
+            text: `cloud config: no @-mention allowlist entry${names.length > 0 ? ` (${names.join(', ')})` : ''} names a usable model in the catalog served to you — ` +
+                'the list is kept as sent, because an empty list would let every model be mentioned; with it, a locally started engine rejects the cloud model settings — at startup it uses its own environment catalog instead, and on a later refresh it keeps the previous configuration',
+        });
+    }
+    out.push(budgetNotice(p.budget));
+    out.push(runtimeCapsNotice(p.runtimeCaps));
+    return out;
+}

package/dist/hitl/frameRouter.d.ts

@@ -1,5 +1,5 @@
 import type { AgentEvent } from '@sema-agent/sdk';
-import type { HitlClientLike } from './hitlBridge.js';
+import type { DecideOperationObserver, HitlClientLike } from './hitlBridge.js';
 import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts, type ToolApprovalFrameOutcome } from './toolApprovalWire.js';
 import type { GateLedger } from './gateLedger.js';
 export declare const HITL_REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
@@ -22,6 +22,7 @@ export interface AskGateWireDeps {
     onParkReattach?: (e: ParkReattachNotice) => void;
     approvalLane?: ToolApprovalFrameLaneOpts;
     onToolApprovalOutcome?: (frame: ToolApprovalFrame, outcome: ToolApprovalFrameOutcome) => void | Promise<void>;
+    onDecideOperation?: DecideOperationObserver;
 }
 export type GateKind = 'ask' | 'fs';
 export interface GatePark {

package/dist/hitl/hitlBridge.d.ts

@@ -64,6 +64,29 @@ export declare class DecideTransportRetryExhaustedError extends Error {
     readonly attempts: number;
     constructor(attempts: number, lastFailureText: string);
 }
+export interface DecideOperationIdentity {
+    readonly operation: object;
+    readonly taskId: string;
+    readonly sessionId: string;
+    readonly boundCallId?: string;
+}
+export interface DecideOperationStart extends DecideOperationIdentity {
+    readonly phase: 'start';
+}
+export interface DecideOperationEnd extends DecideOperationIdentity {
+    readonly phase: 'end';
+    readonly ok: boolean;
+    readonly attempts: number;
+    readonly retryExhausted: boolean;
+}
+export type DecideOperationEvent = DecideOperationStart | DecideOperationEnd;
+export type DecideOperationObserver = (ev: DecideOperationEvent) => void | Promise<void>;
+export interface HitlBridgeOptions {
+    onDecideOperation?: DecideOperationObserver;
+}
+export interface DecideOperationSpan {
+    close(): void;
+}
 export interface ActiveGate {
     gate: CheckpointGate;
     seq?: string | undefined;
@@ -85,7 +108,8 @@ export declare class HitlBridge {
     private readonly client;
     private readonly taskId;
     private active;
-    constructor(client: HitlClientLike, taskId: string);
+    private readonly decideObserver;
+    constructor(client: HitlClientLike, taskId: string, opts?: HitlBridgeOptions);
     observe(ev: AgentEvent): void;
     currentGate(): CheckpointGate | null;
     currentGateReopen(): SuspendedReopenReading | null;
@@ -97,6 +121,7 @@ export declare class HitlBridge {
         remember?: 'session' | undefined;
     } | HitlDecideDenyOutcome, toolUseID?: string, opts?: {
         signal?: AbortSignal;
+        operation?: DecideOperationSpan;
     }, preResolvedPending?: PendingCheckpoint): Promise<unknown>;
     answerQuestion(answers: AskAnswer[], toolUseID?: string, opts?: {
         signal?: AbortSignal;
@@ -108,6 +133,9 @@ export declare class HitlBridge {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;
     private decideRaw;
+    private decideIdentityOf;
+    openDecideOperation(): DecideOperationSpan;
+    private decideRawAttempts;
 }
 export type GatePrompt<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike> = (ctx: {
     toolName: string;