@sema-agent/client-core 0.98.0 → 0.100.0

package/dist/hooksWireCaps.js

@@ -1,7 +1,9 @@
 import { engineCapNestedTrue, engineCapState, engineCapValue } from './engineCapsCache.js';
+import { msg, renderMessage } from './i18n/translate.js';
 import { capForDisplay, collapseLabel } from './fleetTaskDesc.js';
 import { hostLog, hostSettings } from './host.js';
-import { createSettingsHookJudge, decidePluginHooks, dedupeSettingsHookGroups, filterSettingsHookGroups, occupancyOf, } from './pluginHooksWire.js';
+import { hooksSalvageMaskOf, salvageSettingsHooksEntries, settingsHooksSalvageNotice } from './settingsHooksSalvage.js';
+import { createSettingsHookJudge, decidePluginHooks, decideSessionHooks, dedupeSettingsHookGroups, filterSettingsHookGroups, hooksWirePlanShapeOf, occupancyOf, } from './pluginHooksWire.js';
 import { MAX_HOOK_NOTICE_TEXT_CHARS } from './notifications.js';
 import { goalStopHookMatcher, __resetGoalStopHookForTests } from './goalStopHook.js';
 export { GOAL_STOP_HOOK_WIRE_ENV, isGoalStopHookWireArmed, setWireSessionStopHook, getWireSessionStopHook, } from './goalStopHook.js';
@@ -99,15 +101,38 @@ function managedPolicyUnreadable(settings) {
         return true;
     }
 }
-function hooksOfSource(source) {
+const NO_LAYER = Object.freeze({ hooks: null, mask: undefined });
+function layerOfDoc(source, doc) {
     try {
-        const s = hostSettings()?.getSettingsForSource(source);
-        return s?.hooks && typeof s.hooks === 'object' && !Array.isArray(s.hooks) ? s.hooks : null;
+        return classifyLayer(source, doc);
+    }
+    catch (err) {
+        hostLog('debug', `hooksWireCaps: ${source} settings could not be read by the hooks reader — treated as no hooks from this source: ${String(err)}`);
+        return NO_LAYER;
+    }
+}
+function classifyLayer(source, doc) {
+    const salvage = salvageSettingsHooksEntries(doc);
+    const hooks = typeof doc === 'object' && doc !== null && !Array.isArray(doc) ? doc.hooks : undefined;
+    const original = typeof hooks === 'object' && hooks !== null && !Array.isArray(hooks) ? hooks : null;
+    if (salvage.outcome === 'loaded')
+        return { hooks: original, mask: undefined };
+    const notice = settingsHooksSalvageNotice(salvage, source, doc) ?? '';
+    const row = Object.freeze({ source, outcome: salvage.outcome, dropped: salvage.dropped, rejections: salvage.rejections, notice });
+    if (salvage.outcome === 'rejected')
+        return { hooks: null, mask: undefined, row };
+    return { hooks: original, mask: hooksSalvageMaskOf(salvage.dropped), row };
+}
+function layerOfSource(source) {
+    let doc;
+    try {
+        doc = hostSettings()?.getSettingsForSource(source);
     }
     catch (err) {
         hostLog('debug', `hooksWireCaps: ${source} settings read threw — treated as no hooks from this source: ${String(err)}`);
-        return null;
+        return NO_LAYER;
     }
+    return layerOfDoc(source, doc);
 }
 let warnedNoPluginReader = new WeakSet();
 const NO_PLUGIN_READER_WARNING = 'client-core: the installed settings port does not implement enabledPluginHooks() — ' +
@@ -143,32 +168,70 @@ function readPluginHooks(settings, warnIfAbsent) {
     }
     return { state: 'absent' };
 }
-function usageError(tail) {
-    return new TypeError(`hooksForWire: pass { plan } with the plan returned by hooksWirePlan() for this turn — ${tail}`);
+function readSessionHooks(settings) {
+    try {
+        const member = settings.sessionHooks;
+        if (member === undefined)
+            return { state: 'absent' };
+        if (typeof member !== 'function') {
+            hostLog('debug', 'hooksWireCaps: sessionHooks is not a method — no session hooks judged this turn');
+            return { state: 'failed' };
+        }
+        const r = member.call(settings);
+        const sources = typeof r === 'object' && r !== null ? r.sources : undefined;
+        if (Array.isArray(sources))
+            return { state: 'present', sources };
+        hostLog('debug', 'hooksWireCaps: sessionHooks() returned a malformed reading — no session hooks judged this turn');
+        return { state: 'failed' };
+    }
+    catch (err) {
+        hostLog('debug', `hooksWireCaps: sessionHooks() threw — no session hooks judged this turn: ${String(err)}`);
+        return { state: 'failed' };
+    }
+}
+function suppressedLocallyOf(o) {
+    let raw;
+    try {
+        raw = o.suppressedLocally;
+    }
+    catch {
+        hostLog('debug', 'hooksWirePlan: suppressedLocally threw while being read — treated as absent (no plugin suppressed locally)');
+        return undefined;
+    }
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw) || !raw.every((x) => typeof x === 'string')) {
+        hostLog('debug', 'hooksWirePlan: suppressedLocally is not an array of plugin ids — treated as absent (no plugin suppressed locally)');
+        return undefined;
+    }
+    return new Set(raw);
+}
+function usageError(sentence) {
+    return new TypeError(renderMessage(sentence));
 }
 function hostValueShape(v) {
     try {
         if (v === undefined)
-            return 'nothing';
+            return msg('config.hooks.valueShape.nothing');
         if (v === null)
-            return 'null';
+            return msg('config.hooks.valueShape.null');
         if (Array.isArray(v))
-            return 'an array';
-        return typeof v === 'object' ? 'an object' : `a ${typeof v}`;
+            return msg('config.hooks.valueShape.array');
+        return typeof v === 'object' ? msg('config.hooks.valueShape.object') : msg('config.hooks.valueShape.typeof', { type: typeof v });
     }
     catch {
-        return 'unreadable';
+        return msg('config.hooks.valueShape.unreadable');
     }
 }
 export function hooksForWire(opts) {
     if (typeof opts !== 'object' || opts === null)
-        throw usageError(`got ${hostValueShape(opts)}.`);
+        throw usageError(msg('config.hooks.forWire.gotShape', { shape: hostValueShape(opts) }));
     let given;
     try {
         given = opts.plan;
     }
     catch {
-        throw usageError(`reading opts.plan threw.`);
+        throw usageError(msg('config.hooks.forWire.readPlanThrew'));
     }
     const shape = planShapeOf(given);
     if (shape === 'plan') {
@@ -176,46 +239,16 @@ export function hooksForWire(opts) {
             return given.wire;
         }
         catch {
-            throw usageError(`reading the plan's wire threw.`);
+            throw usageError(msg('config.hooks.forWire.readWireThrew'));
         }
     }
     if (shape === 'threw')
-        throw usageError(`opts.plan could not be read as a plan.`);
+        throw usageError(msg('config.hooks.forWire.planUnreadable'));
     if (given === undefined && planShapeOf(opts) === 'plan')
-        throw usageError(`the plan itself was passed; wrap it as { plan }.`);
-    throw usageError(`opts.plan is ${given === undefined ? 'missing' : `not such a plan (got ${hostValueShape(given)})`}.`);
+        throw usageError(msg('config.hooks.forWire.planPassedBare'));
+    throw usageError(given === undefined ? msg('config.hooks.forWire.planMissing') : msg('config.hooks.forWire.planNotPlan', { shape: hostValueShape(given) }));
 }
-function planShapeOf(v) {
-    try {
-        if (typeof v !== 'object' || v === null || Array.isArray(v))
-            return 'not';
-        const o = v;
-        for (const k of PLAN_KEYS)
-            if (!Object.hasOwn(o, k) && k !== 'settingsVerdicts' && k !== 'settingsExcluded')
-                return 'not';
-        const reader = o.pluginReader;
-        const engineFacts = o.engine;
-        const wire = o.wire;
-        const arrayOrAbsent = (k) => !Object.hasOwn(o, k) || Array.isArray(o[k]);
-        return Array.isArray(o.verdicts) &&
-            Array.isArray(o.excluded) &&
-            Array.isArray(o.settingsDropped) &&
-            arrayOrAbsent('settingsVerdicts') &&
-            arrayOrAbsent('settingsExcluded') &&
-            (reader === 'present' || reader === 'absent' || reader === 'failed') &&
-            typeof engineFacts === 'object' &&
-            engineFacts !== null &&
-            (wire === undefined || (typeof wire === 'object' && wire !== null && !Array.isArray(wire)))
-            ? 'plan'
-            : 'not';
-    }
-    catch {
-        return 'threw';
-    }
-}
-const PLAN_KEYS = ['engine', 'pluginReader', 'verdicts', 'excluded', 'settingsDropped', 'settingsVerdicts', 'settingsExcluded', 'wire'];
-const _planKeysPin = [true, true];
-void _planKeysPin;
+const planShapeOf = hooksWirePlanShapeOf;
 export function hooksWirePlan(opts = {}) {
     const o = opts ?? {};
     const owned = o.engineOwnedByThisShell;
@@ -241,7 +274,7 @@ export function hooksWirePlan(opts = {}) {
         const types = typesByEvent.get(event);
         return types === undefined || (typeof type === 'string' && types.has(type));
     };
-    return buildHooksWirePlan(engine, shellRuns, promptAuthoredByUserOf(o));
+    return buildHooksWirePlan(engine, shellRuns, promptAuthoredByUserOf(o), suppressedLocallyOf(o));
 }
 function taskHooksCapability(baseUrl) {
     const v = engineCapValue(baseUrl, 'taskSettings');
@@ -292,14 +325,34 @@ function promptAuthoredByUserOf(o) {
     }
     return true;
 }
-function buildHooksWirePlan(engine, shellRuns, promptAuthoredByUser) {
+function buildHooksWirePlan(engine, shellRuns, promptAuthoredByUser, suppressedLocally) {
     const settingsDropped = [];
     const settingsVerdicts = [];
     const settingsExcluded = [];
+    const settingsSalvage = [];
+    let sessionVerdicts = [];
+    let sessionReader = 'absent';
+    let closedBy = null;
     const judge = createSettingsHookJudge(engine, shellRuns, promptAuthoredByUser);
     let settingsStripped = 0;
-    const planOf = (pluginReader, wire, verdicts = [], excluded = []) => ({ engine, pluginReader, verdicts, excluded, settingsDropped, settingsVerdicts, settingsExcluded, wire });
+    const planOf = (pluginReader, wire, verdicts = [], excluded = [], moduleVerdicts = []) => ({
+        engine,
+        pluginReader,
+        verdicts,
+        excluded,
+        settingsDropped,
+        settingsVerdicts,
+        settingsExcluded,
+        settingsSalvage,
+        moduleVerdicts,
+        sessionVerdicts,
+        sessionReader,
+        closedBy,
+        wire,
+    });
     const closedPlan = (settings, reason) => {
+        closedBy = reason;
+        sessionReader = readSessionHooks(settings).state;
         const read = readPluginHooks(settings, false);
         if (read.reading === undefined)
             return planOf(read.state, undefined);
@@ -333,13 +386,28 @@ function buildHooksWirePlan(engine, shellRuns, promptAuthoredByUser) {
     if (managedPolicyUnreadable(settings))
         return closedPlan(settings, 'governance_unreadable');
     let policy = null;
+    let policyDoc;
     try {
-        policy = settings.getSettingsForSource('policySettings');
+        policyDoc = settings.getSettingsForSource('policySettings');
+        policy = policyDoc;
     }
     catch (err) {
         hostLog('debug', `hooksWireCaps: policySettings read threw — fail-closed (no hooks projected to the engine): ${String(err)}`);
         return closedPlan(settings, 'governance_unreadable');
     }
+    let policyLayer;
+    try {
+        policyLayer = classifyLayer('policySettings', policyDoc);
+    }
+    catch (err) {
+        hostLog('debug', `hooksWireCaps: managed settings could not be read by the hooks reader — fail-closed (no hooks projected to the engine): ${String(err)}`);
+        return closedPlan(settings, 'governance_unreadable');
+    }
+    if (policyLayer.row?.outcome === 'rejected') {
+        settingsSalvage.push(policyLayer.row);
+        hostLog('debug', 'hooksWireCaps: managed settings hooks rejected by the hooks reader — fail-closed (no hooks projected to the engine)');
+        return closedPlan(settings, 'governance_unreadable');
+    }
     if (policy?.disableAllHooks === true) {
         hostLog('debug', 'hooksWireCaps: disableAllHooks (managed) — no hooks projected to the engine');
         return closedPlan(settings, 'policy_disable_all');
@@ -356,6 +424,21 @@ function buildHooksWirePlan(engine, shellRuns, promptAuthoredByUser) {
         hostLog('debug', 'hooksWireCaps: disableAllHooks (merged, non-managed) — only policySettings hooks projected to the engine');
     }
     const managedOnly = managedByPolicy || disabledByNonManaged;
+    {
+        const sr = readSessionHooks(settings);
+        sessionReader = sr.state;
+        if (sr.sources !== undefined && !managedOnly) {
+            const sources = sr.sources;
+            const ds = guardPluginTraversal(() => decideSessionHooks({ sources, engine, shellRuns, promptAuthoredByUser }));
+            if (ds === undefined)
+                sessionReader = 'failed';
+            else {
+                sessionVerdicts = ds.verdicts;
+                if (ds.unreadable > 0)
+                    hostLog('debug', `hooksWireCaps: ${ds.unreadable} session hook source(s) or group(s) unreadable — skipped`);
+            }
+        }
+    }
     const read = readPluginHooks(settings, true);
     let oldStartupBit;
     let pluginDataThrew = false;
@@ -378,13 +461,18 @@ function buildHooksWirePlan(engine, shellRuns, promptAuthoredByUser) {
     const merged = {};
     const sourced = new Map();
     for (const source of sources) {
-        const hooks = hooksOfSource(source);
+        const layer = source === 'policySettings' ? policyLayer : layerOfSource(source);
+        if (layer.row !== undefined)
+            settingsSalvage.push(layer.row);
+        const hooks = layer.hooks;
         if (!hooks)
             continue;
         for (const [event, groups] of Object.entries(hooks)) {
+            if (layer.mask !== undefined && layer.mask.eventDropped(event))
+                continue;
             if (!Array.isArray(groups) || groups.length === 0)
                 continue;
-            const kept = filterSettingsHookGroups(source, event, groups, engine.pluginHooksCapable === true, (type) => shellRuns(event, type), judge);
+            const kept = filterSettingsHookGroups(source, event, groups, engine.pluginHooksCapable === true, (type) => shellRuns(event, type), judge, layer.mask);
             settingsDropped.push(...kept.drops);
             settingsVerdicts.push(...kept.verdicts);
             settingsExcluded.push(...kept.excluded);
@@ -441,6 +529,7 @@ function buildHooksWirePlan(engine, shellRuns, promptAuthoredByUser) {
             shellRuns,
             promptAuthoredByUser,
             occupied,
+            ...(suppressedLocally !== undefined ? { suppressedLocally } : {}),
         });
     });
     if (d === undefined)
@@ -450,7 +539,7 @@ function buildHooksWirePlan(engine, shellRuns, promptAuthoredByUser) {
     }
     for (const [event, groups] of d.projected)
         merged[event] = [...(merged[event] ?? []), ...groups];
-    return planOf('present', wireOf(), d.verdicts, d.excluded);
+    return planOf('present', wireOf(), d.verdicts, d.excluded, d.modules);
 }
 export function __resetHooksWireCapsForTests() {
     __resetGoalStopHookForTests();

package/dist/host.d.ts

@@ -9,6 +9,7 @@ export interface SettingsPort {
     enabledPluginHooks?(): PluginHooksReading;
     hooksStartupMode?(): HooksStartupMode | undefined;
     managedPolicyReading?(): ManagedPolicyReading;
+    sessionHooks?(): SessionHooksReading;
 }
 export type ManagedPolicyState = 'absent' | 'in-effect' | 'unreadable';
 export interface ManagedPolicyReading {
@@ -32,6 +33,26 @@ export interface PluginHookSource {
     readonly managed: boolean;
     readonly options?: Readonly<Record<string, PluginHookOption>>;
     readonly hooks: WireHooksConfig;
+    readonly hooksModule?: boolean;
+}
+export type SessionHookOrigin = 'skill' | 'agent' | 'sdk_host';
+export interface SessionHookSource {
+    readonly origin: SessionHookOrigin;
+    readonly name: string;
+    readonly hooks: WireHooksConfig | {
+        readonly [event: string]: readonly {
+            readonly matcher?: string;
+            readonly hooks: readonly (NonNullable<WireHooksConfig[string]>[number]['hooks'][number] | SessionLocalHook)[];
+        }[] | undefined;
+    };
+}
+export interface SessionLocalHook {
+    readonly type: 'callback' | 'function';
+    readonly callback?: (...args: never[]) => void;
+    readonly timeout?: number;
+}
+export interface SessionHooksReading {
+    readonly sources: readonly SessionHookSource[];
 }
 export interface PluginHooksReading {
     readonly plugins: readonly PluginHookSource[];

package/dist/hostTurnSettings.d.ts

@@ -0,0 +1,110 @@
+import type { TaskRequest } from '@sema-agent/sdk';
+import type { WireHooksConfig } from './finalVerifyWire.js';
+import type { memoryOffDeclared as MemoryOffDeclared } from './request/taskRequest.js';
+import type { EnvLike } from './hostEnv.js';
+import type { SettingsDocument } from './host.js';
+import { type HookSettingsSource, type HooksWirePlan } from './pluginHooksWire.js';
+import { type WebSearchApiKeyFor } from './webSearchWireCaps.js';
+import { type FileHistoryCaptureReading } from './fileHistoryCaptureCapability.js';
+export declare const HOST_SUPPLIED_KEYS: readonly ["settings.hooks", "settings.resolved", "settings.webSearch", "settings.outputStyle", "memory", "fileHistory"];
+export type HostSuppliedKey = (typeof HOST_SUPPLIED_KEYS)[number];
+export declare const HOST_SETTING_CAUSES: readonly ["carried", "entries_dropped", "source_rejected", "projection_failed", "source_unreadable", "empty", "no_source", "host_port_missing", "value_malformed"];
+export type HostSettingCause = (typeof HOST_SETTING_CAUSES)[number];
+export declare const HOST_SETTING_DISPOSITIONS: readonly ["carry", "carry_partial", "withhold_notice", "refuse_turn", "unwired", "nothing_to_carry"];
+export type HostSettingDisposition = (typeof HOST_SETTING_DISPOSITIONS)[number];
+export type HostSettingPlane = 'turn' | 'session' | 'diagnostic';
+export type HostSettingNoticeId = 'HS-UNWIRED' | 'HS-MANAGED-REJECTED' | 'HS-PROJECTION' | 'HS-SOURCE-UNREADABLE' | 'HS-WEBSEARCH-MALFORMED' | 'HS-SWITCH-MALFORMED' | 'HS-FILEHISTORY-UNJUDGED';
+export interface HostSettingRow {
+    readonly key: HostSuppliedKey;
+    readonly cause: HostSettingCause;
+    readonly disposition: HostSettingDisposition;
+    readonly layers?: readonly HookSettingsSource[];
+}
+export interface HostSettingNotice {
+    readonly id: HostSettingNoticeId;
+    readonly plane: HostSettingPlane;
+    readonly text: string;
+}
+export type HostTurnVerdict = {
+    readonly kind: 'send';
+} | {
+    readonly kind: 'refuse';
+    readonly notice: HostSettingNotice;
+};
+export interface HostTurnSettingsSources {
+    readonly hooks: {
+        readonly plan: HooksWirePlan;
+    } | 'none';
+    readonly resolved: {
+        readonly snapshot: SettingsDocument;
+    } | 'none';
+    readonly webSearch: HostWebSearchSource | 'none';
+    readonly outputStyle: {
+        readonly name: string;
+    } | 'none';
+    readonly memory: HostMemorySource | 'none';
+    readonly fileHistory: {
+        readonly reading: FileHistoryCaptureReading;
+        readonly captureOff: boolean;
+    } | 'none';
+}
+export interface HostWebSearchSource {
+    readonly section?: SettingsDocument;
+    readonly env: EnvLike;
+    readonly apiKeyFor?: WebSearchApiKeyFor;
+}
+export interface HostMemorySource {
+    readonly flag?: string;
+    readonly settingsMemory?: SettingsDocument;
+}
+export interface HostTurnSettingsInput {
+    readonly sources: HostTurnSettingsSources;
+}
+export interface HostSettingsCarried {
+    readonly hooks?: WireHooksConfig;
+    readonly resolved?: SettingsDocument;
+    readonly webSearch?: SettingsDocument;
+    readonly outputStyle?: string;
+    readonly memory?: TaskRequest['memory'];
+    readonly fileHistory?: TaskRequest['fileHistory'];
+}
+declare const hostTurnSettingsBrand: unique symbol;
+export interface HostTurnSettings {
+    readonly [hostTurnSettingsBrand]: true;
+    readonly verdict: HostTurnVerdict;
+    readonly rows: readonly HostSettingRow[];
+    readonly notices: readonly HostSettingNotice[];
+    readonly hooks: HooksWirePlan | undefined;
+    readonly carried: HostSettingsCarried;
+}
+export interface HostTurnSettingsJudges {
+    readonly materialize: HostResolvedMaterializer;
+    readonly memoryOffDeclared: typeof MemoryOffDeclared;
+}
+export declare function rethrowHostResolvedDeferred(product: HostTurnSettings): void;
+export type HostResolvedMaterializer = (snapshot: SettingsDocument) => SettingsDocument;
+export declare function buildHostTurnSettings(input: HostTurnSettingsInput, judges: HostTurnSettingsJudges): HostTurnSettings;
+export declare function hostSettingsSelfCheck(product: HostTurnSettings): readonly HostSuppliedKey[];
+export declare const hostProjectionNotice: () => HostSettingNotice;
+export declare class HostSettingsRefused extends Error {
+    readonly notice: HostSettingNotice;
+    constructor(n: HostSettingNotice);
+}
+export declare function hostTurnSettingsOf(v: unknown, depth?: 'shape' | 'full'): HostTurnSettings | undefined;
+export interface HostHooksIntersection {
+    readonly hooks: WireHooksConfig | undefined;
+    readonly dropped: number;
+    readonly judged: boolean;
+}
+export declare function intersectHostHooks(sent: WireHooksConfig, now: WireHooksConfig | undefined): HostHooksIntersection;
+export interface HostIntakeSnapshot {
+    readonly carried: HostSettingsCarried;
+    readonly refuses: boolean;
+    readonly dispositions: Readonly<Record<HostSuppliedKey, HostSettingDisposition>>;
+    readonly refusingKeys: readonly HostSuppliedKey[];
+    readonly turnNotices: readonly HostSettingNotice[] | undefined;
+    readonly notice: HostSettingNotice | undefined;
+}
+export declare function hostIntakeSnapshotOf(product: HostTurnSettings, onResolved?: (resolved: HostSettingsCarried['resolved']) => void): HostIntakeSnapshot | undefined;
+export declare const UNWIRED_HOST_TURN_SETTINGS: HostTurnSettings;
+export {};