@sema-agent/client-core 0.88.0 → 0.90.0

package/dist/permissionsAllowGrantCapability.js

@@ -0,0 +1,75 @@
+import { engineWireTarget } from './engineWireTarget.js';
+import { createEngineCapReader } from './engineCapReader.js';
+const ALLOW_GRANT_CAP_PATH = ['settings', 'permissions', 'allowGrant'];
+export function projectPermissionsAllowGrantCapability(caps) {
+    if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
+        return undefined;
+    let node = caps;
+    for (let i = 0; i < ALLOW_GRANT_CAP_PATH.length; i++) {
+        const seg = ALLOW_GRANT_CAP_PATH[i];
+        if (!Object.hasOwn(node, seg))
+            return { kind: 'not_reported' };
+        const v = node[seg];
+        if (v === undefined)
+            return { kind: 'not_reported' };
+        if (i === ALLOW_GRANT_CAP_PATH.length - 1) {
+            return typeof v === 'boolean' ? { kind: 'present', grants: v } : undefined;
+        }
+        if (v === null || typeof v !== 'object' || Array.isArray(v))
+            return undefined;
+        node = v;
+    }
+    return undefined;
+}
+const reader = createEngineCapReader({
+    name: ALLOW_GRANT_CAP_PATH.join('.'),
+    project: projectPermissionsAllowGrantCapability,
+    makeUnobserved: () => ({ kind: 'unobserved' }),
+});
+export function noteEngineCapsForPermissionsAllowGrant(baseUrl, caps, opts) {
+    reader.note(baseUrl, caps, opts);
+}
+export function observedPermissionsAllowGrant(baseUrl = engineWireTarget()?.baseUrl) {
+    return reader.observed(baseUrl);
+}
+export function permissionsAllowGrantAvailable(reading) {
+    try {
+        if (reading === null || typeof reading !== 'object' || Array.isArray(reading))
+            return false;
+        if (!Object.hasOwn(reading, 'kind') || !Object.hasOwn(reading, 'grants'))
+            return false;
+        return reading.kind === 'present' && reading.grants === true;
+    }
+    catch {
+        return false;
+    }
+}
+function ownReadingField(reading, key) {
+    try {
+        if (reading === null || typeof reading !== 'object' || Array.isArray(reading))
+            return undefined;
+        return Object.hasOwn(reading, key) ? reading[key] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function permissionsAllowGrantDoctorDetail(reading) {
+    if (permissionsAllowGrantAvailable(reading)) {
+        return 'allow rules sent to the engine — it reads them as rules, not as an exclusive list: a matching call counts as answered for, and the engine still raises its own prompts where it requires them';
+    }
+    const kind = ownReadingField(reading, 'kind');
+    if (kind === 'present' && ownReadingField(reading, 'grants') === false) {
+        return 'allow rules kept on this side — this engine says it does not read allow rules as rules of that kind, so they are not sent and matching approvals are still answered here';
+    }
+    if (kind === 'not_reported') {
+        return 'allow rules kept on this side — this engine does not say how it reads allow rules; sending them to an engine that reads them as an exclusive list would block every tool not on it, so they are not sent and matching approvals are still answered here';
+    }
+    return 'allow rules kept on this side — no usable capabilities reading is cached for this engine (none received, or the last one was unreadable), so allow rules are not sent and matching approvals are still answered here';
+}
+export function forgetPermissionsAllowGrantReading(baseUrl) {
+    reader.forget(baseUrl);
+}
+export function __resetPermissionsAllowGrantReadingsForTests() {
+    reader.__resetForTests();
+}

package/dist/permissionsDeclaration.d.ts

@@ -0,0 +1,25 @@
+import { type PermissionsAllowGrantReading } from './permissionsAllowGrantCapability.js';
+declare const RULE_TRUST_ORDER: readonly ["policySettings", "cliArg", "flagSettings", "session", "userSettings", "localSettings", "projectSettings"];
+export type WireRuleOrigin = (typeof RULE_TRUST_ORDER)[number];
+export interface WireRuleOrigins {
+    readonly deny?: ReadonlyMap<string, WireRuleOrigin>;
+    readonly ask?: ReadonlyMap<string, WireRuleOrigin>;
+    readonly allow?: ReadonlyMap<string, WireRuleOrigin>;
+}
+export interface PermissionsDeclarationInput {
+    readonly deny: readonly string[];
+    readonly ask: readonly string[];
+    readonly allow: readonly string[];
+    readonly origins?: WireRuleOrigins;
+    readonly cliDeny?: readonly string[];
+}
+export interface PermissionsDeclarationBuckets {
+    deny?: string[];
+    ask?: string[];
+    allow?: string[];
+}
+export interface PermissionsDeclaration {
+    permissions?: PermissionsDeclarationBuckets;
+}
+export declare function permissionsDeclaration(input: PermissionsDeclarationInput, caps: PermissionsAllowGrantReading): PermissionsDeclaration;
+export {};

package/dist/permissionsDeclaration.js

@@ -0,0 +1,227 @@
+import { hasCoreValuePort, protocolOf, retiredToolNames, ruleToolGrammarOf, validatePermissionRules } from './coreValuePorts.js';
+import { permissionsAllowGrantAvailable } from './permissionsAllowGrantCapability.js';
+const RULE_TRUST_ORDER = [
+    'policySettings',
+    'cliArg',
+    'flagSettings',
+    'session',
+    'userSettings',
+    'localSettings',
+    'projectSettings',
+];
+function normalizeLegacyToolName(name) {
+    switch (name) {
+        case 'Task':
+            return 'Agent';
+        case 'KillShell':
+            return 'TaskStop';
+        case 'AgentOutputTool':
+        case 'BashOutputTool':
+            return 'TaskOutput';
+        default:
+            return name;
+    }
+}
+function unescapedIndex(str, char, fromEnd) {
+    for (let k = 0; k < str.length; k++) {
+        const i = fromEnd ? str.length - 1 - k : k;
+        if (str[i] !== char)
+            continue;
+        let backslashes = 0;
+        for (let j = i - 1; j >= 0 && str[j] === '\\'; j--)
+            backslashes++;
+        if (backslashes % 2 === 0)
+            return i;
+    }
+    return -1;
+}
+function unescapeRuleContent(content) {
+    return content.replace(/\\\(/g, '(').replace(/\\\)/g, ')').replace(/\\\\/g, '\\');
+}
+function parseRule(rule) {
+    const open = unescapedIndex(rule, '(', false);
+    if (open === -1)
+        return { toolName: normalizeLegacyToolName(rule) };
+    const close = unescapedIndex(rule, ')', true);
+    if (close === -1 || close <= open || close !== rule.length - 1)
+        return { toolName: normalizeLegacyToolName(rule) };
+    const toolName = rule.substring(0, open);
+    const rawContent = rule.substring(open + 1, close);
+    if (!toolName)
+        return { toolName: normalizeLegacyToolName(rule) };
+    if (rawContent === '' || rawContent === '*')
+        return { toolName: normalizeLegacyToolName(toolName) };
+    return { toolName: normalizeLegacyToolName(toolName), ruleContent: unescapeRuleContent(rawContent) };
+}
+function requireRulePorts() {
+    const required = ['MCP_NAMESPACE', 'RETIRED_TOOL_NAMES', 'protocolOf', 'ruleToolGrammarOf', 'validatePermissionRules'];
+    const missing = required.filter((p) => !hasCoreValuePort(p));
+    if (missing.length === 0)
+        return;
+    throw new Error(`permissionsDeclaration: 规则判据端口缺席(${missing.join(' / ')})—— 先用 installCoreValuePorts 装上 core 的同名实现。` +
+        '缺席不等于全部合格:不判就发会让整份请求被引擎拒收,不判就删会静默丢掉 deny 规则,所以这里拒绝装配。');
+}
+function engineWireSafe(name) {
+    if (name.includes('('))
+        return false;
+    if (retiredToolNames().has(name))
+        return false;
+    const ns = protocolOf(name);
+    if (ns === undefined)
+        return !name.includes('__');
+    return ns.parse(name) !== undefined;
+}
+function wholeServerRuleName(name) {
+    const read = name.trim();
+    const ns = protocolOf(read);
+    if (ns === undefined || !read.startsWith(ns.prefix))
+        return name;
+    const peer = read.slice(ns.prefix.length);
+    return peer !== '' && !peer.includes('__') && !peer.endsWith('_') ? `${read}__*` : name;
+}
+const RULE_ROOT = '/';
+function compileVerdict(rule, behavior) {
+    try {
+        const issues = validatePermissionRules([{ rule, behavior }], { pathBases: { root: RULE_ROOT } });
+        if (!Array.isArray(issues))
+            return 'unknown';
+        return issues.length === 0 ? 'compiles' : 'refused';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function wireSubset(rules, behavior) {
+    const out = new Set();
+    let portsChecked = false;
+    for (const rule of rules) {
+        if (typeof rule !== 'string' || rule === '')
+            continue;
+        if (!portsChecked) {
+            requireRulePorts();
+            portsChecked = true;
+        }
+        const parsed = parseRule(rule);
+        if (parsed.ruleContent === undefined) {
+            const name = wholeServerRuleName(parsed.toolName);
+            if (!engineWireSafe(name))
+                continue;
+            if (out.has(name))
+                continue;
+            const verdict = compileVerdict(name, behavior);
+            if (verdict === 'refused' || (verdict === 'unknown' && behavior === 'allow'))
+                continue;
+            out.add(name);
+            continue;
+        }
+        if (!engineWireSafe(parsed.toolName))
+            continue;
+        if (ruleToolGrammarOf(parsed.toolName) === 'path' && parsed.ruleContent.startsWith('~/'))
+            continue;
+        const verdict = compileVerdict(rule, behavior);
+        if (verdict === 'compiles' || (verdict === 'unknown' && behavior !== 'allow'))
+            out.add(rule);
+    }
+    return [...out];
+}
+function projectBucketByTrust(raw, behavior, originOf, cliRules) {
+    const present = new Set(raw);
+    const groups = RULE_TRUST_ORDER.map(() => []);
+    const rankOf = (origin) => RULE_TRUST_ORDER.indexOf(origin);
+    if (originOf !== undefined) {
+        for (const [r, origin] of originOf) {
+            const rank = rankOf(origin);
+            if (rank >= 0 && typeof r === 'string' && present.has(r))
+                groups[rank].push(r);
+        }
+    }
+    const unknownOrigin = [...present].filter((r) => originOf === undefined || rankOf(originOf.get(r)) < 0);
+    const out = new Set();
+    const append = (list) => {
+        for (const r of list)
+            out.add(r);
+    };
+    RULE_TRUST_ORDER.forEach((origin, rank) => {
+        if (origin === 'cliArg')
+            append(cliRules);
+        append(wireSubset(groups[rank], behavior));
+    });
+    append(wireSubset(unknownOrigin, behavior));
+    return [...out];
+}
+const WHO = 'permissionsDeclaration';
+function ownField(obj, key, where) {
+    if (Object.hasOwn(obj, key))
+        return obj[key];
+    if (key in obj)
+        throw new TypeError(`${WHO}: ${where}${key} 只在原型链上,不是自有字段 —— 拒绝读取(请交普通对象)。`);
+    return undefined;
+}
+function ruleList(v, key) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (!Array.isArray(v))
+        throw new TypeError(`${WHO}: ${key} 必须是规则串数组或缺席 —— 收到 typeof=${typeof v}。`);
+    const out = [];
+    const n = v.length;
+    for (let i = 0; i < n; i++) {
+        if (!Object.hasOwn(v, i)) {
+            if (i in v)
+                throw new TypeError(`${WHO}: ${key}[${i}] 是空洞,而原型链上在这个下标有值 —— 拒绝读取(请交不带空洞的普通数组)。`);
+            continue;
+        }
+        const r = v[i];
+        if (typeof r === 'string')
+            out.push(r);
+    }
+    return out;
+}
+function originMap(v, key) {
+    if (v === undefined || v === null)
+        return undefined;
+    const ok = typeof v === 'object' &&
+        typeof v.get === 'function' &&
+        typeof v[Symbol.iterator] === 'function';
+    if (!ok)
+        throw new TypeError(`${WHO}: origins.${key} 必须是 Map(规则原串 → 来源)或缺席 —— 收到 typeof=${typeof v}。`);
+    const snap = new Map();
+    for (const entry of v) {
+        const [r, origin] = entry;
+        if (!snap.has(r))
+            snap.set(r, origin);
+    }
+    return snap;
+}
+export function permissionsDeclaration(input, caps) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError(`${WHO}: 入参必须是对象 —— 收到 ${input === null ? 'null' : Array.isArray(input) ? 'array' : `typeof=${typeof input}`}。`);
+    }
+    const deny = ruleList(ownField(input, 'deny', ''), 'deny');
+    const ask = ruleList(ownField(input, 'ask', ''), 'ask');
+    const allow = ruleList(ownField(input, 'allow', ''), 'allow');
+    const cliDeny = ruleList(ownField(input, 'cliDeny', ''), 'cliDeny');
+    const originsRaw = ownField(input, 'origins', '');
+    let origins = {};
+    if (originsRaw !== undefined && originsRaw !== null) {
+        if (typeof originsRaw !== 'object' || Array.isArray(originsRaw)) {
+            throw new TypeError(`${WHO}: origins 必须是 { deny?, ask?, allow? } 对象或缺席 —— 收到 typeof=${typeof originsRaw}。`);
+        }
+        const od = originMap(ownField(originsRaw, 'deny', 'origins.'), 'deny');
+        const oa = originMap(ownField(originsRaw, 'ask', 'origins.'), 'ask');
+        const ol = originMap(ownField(originsRaw, 'allow', 'origins.'), 'allow');
+        origins = { ...(od ? { deny: od } : {}), ...(oa ? { ask: oa } : {}), ...(ol ? { allow: ol } : {}) };
+    }
+    const allowOn = permissionsAllowGrantAvailable(caps);
+    const cliDenyWire = cliDeny === undefined ? [] : wireSubset(cliDeny, 'deny');
+    const denyOut = projectBucketByTrust(deny ?? [], 'deny', origins.deny, cliDenyWire);
+    const askOut = projectBucketByTrust(ask ?? [], 'ask', origins.ask, []);
+    const allowOut = allowOn && allow !== undefined ? projectBucketByTrust(allow, 'allow', origins.allow, []) : [];
+    const permissions = {};
+    if (denyOut.length > 0)
+        permissions.deny = denyOut;
+    if (askOut.length > 0)
+        permissions.ask = askOut;
+    if (allowOut.length > 0)
+        permissions.allow = allowOut;
+    return Object.keys(permissions).length > 0 ? { permissions } : {};
+}

package/dist/pluginHooksWire.d.ts

@@ -4,9 +4,9 @@ export declare const ENGINE_FIRED_HOOK_EVENTS: readonly ["PreToolUse", "PostTool
 export type EngineFiredHookEvent = (typeof ENGINE_FIRED_HOOK_EVENTS)[number];
 export declare const PLUGIN_HOOK_DISPOSITIONS: readonly ["engine", "shell", "not_run"];
 export type PluginHookDisposition = (typeof PLUGIN_HOOK_DISPOSITIONS)[number];
-export declare const PLUGIN_HOOK_REASONS: readonly ["projected", "shell_event", "no_executor", "engine_not_local", "engine_locality_unknown", "engine_capability_absent", "engine_capability_unknown", "not_command", "sensitive_options", "engine_limit", "shell_form_user_config", "user_config_unset", "malformed_entry"];
+export declare const PLUGIN_HOOK_REASONS: readonly ["projected", "shell_event", "no_executor", "engine_not_local", "engine_locality_unknown", "engine_capability_absent", "engine_capability_unknown", "not_command", "sensitive_options", "engine_limit", "shell_form_user_config", "user_config_unset", "malformed_entry", "engine_hooks_off", "engine_hooks_unknown", "engine_type_skipped", "engine_llm_limit", "engine_unconfirmed", "engine_elsewhere"];
 export type PluginHookReason = (typeof PLUGIN_HOOK_REASONS)[number];
-export declare const PLUGIN_HOOK_EXCLUSION_REASONS: readonly ["workspace_untrusted", "governance_unreadable", "policy_disable_all", "startup_mode", "managed_plugins_only"];
+export declare const PLUGIN_HOOK_EXCLUSION_REASONS: readonly ["workspace_untrusted", "governance_unreadable", "policy_disable_all", "startup_mode", "managed_plugins_only", "prompt_not_user_authored"];
 export type PluginHookExclusionReason = (typeof PLUGIN_HOOK_EXCLUSION_REASONS)[number];
 export declare const SETTINGS_HOOK_DROP_REASONS: readonly ["exec_form_unsupported", "mcp_tool_unsupported"];
 export type SettingsHookDropReason = (typeof SETTINGS_HOOK_DROP_REASONS)[number];
@@ -33,9 +33,25 @@ export interface SettingsHookDrop {
     readonly reason: SettingsHookDropReason;
     readonly notRun: boolean;
 }
+export interface SettingsHookVerdict {
+    readonly source: HookSettingsSource;
+    readonly event: string;
+    readonly groupIndex: number;
+    readonly hookIndex: number;
+    readonly disposition: PluginHookDisposition;
+    readonly reason: PluginHookReason;
+}
+export interface SettingsHookExclusion {
+    readonly source: HookSettingsSource;
+    readonly event: string;
+    readonly groupIndex: number;
+    readonly hookIndex: number;
+    readonly reason: PluginHookExclusionReason;
+}
 export interface HooksWireEngineFacts {
     readonly ownedByThisShell: boolean | null;
     readonly pluginHooksCapable: boolean | null;
+    readonly hooksCapable: boolean | null;
 }
 export type PluginHookReaderState = 'present' | 'absent' | 'failed';
 export interface HooksWirePlan {
@@ -44,19 +60,34 @@ export interface HooksWirePlan {
     readonly verdicts: readonly PluginHookVerdict[];
     readonly excluded: readonly PluginHookExclusion[];
     readonly settingsDropped: readonly SettingsHookDrop[];
+    readonly settingsVerdicts: readonly SettingsHookVerdict[];
+    readonly settingsExcluded: readonly SettingsHookExclusion[];
     readonly wire: WireHooksConfig | undefined;
 }
 export interface HooksWirePlanOptions {
     readonly baseUrl?: string;
     readonly engineOwnedByThisShell?: boolean;
     readonly shellHookEvents?: readonly string[];
+    readonly shellHookTypesByEvent?: Readonly<Record<string, readonly string[]>>;
+    readonly promptAuthoredByUser?: boolean;
 }
 export declare const ENGINE_HOOK_LIMITS: {
     readonly maxGroupsPerEvent: 16;
     readonly maxEntriesPerEvent: 32;
     readonly maxCommandChars: 8192;
+    readonly maxLlmEntriesPerEvent: 4;
+};
+export type ShellRunsHook = (event: string, type: string | undefined) => boolean;
+type HookExecutor = {
+    readonly kind: 'excluded';
+    readonly reason: 'prompt_not_user_authored';
+} | {
+    readonly kind: 'judged';
+    readonly disposition: PluginHookDisposition;
+    readonly reason: PluginHookReason;
 };
 type WireHookGroup = NonNullable<WireHooksConfig[string]>[number];
+type WireHookEntry = WireHookGroup['hooks'][number];
 export declare function isEngineFiredHookEvent(event: string): boolean;
 export interface EventOccupancy {
     readonly groups: number;
@@ -68,7 +99,8 @@ export interface PluginHookDecisionInput {
     readonly exclusion: PluginHookExclusionReason | undefined;
     readonly managedOnly: boolean;
     readonly engine: HooksWireEngineFacts;
-    readonly shellHookEvents: ReadonlySet<string>;
+    readonly shellRuns: ShellRunsHook;
+    readonly promptAuthoredByUser: boolean;
     readonly occupied: ReadonlyMap<string, EventOccupancy>;
 }
 export interface PluginHookDecision {
@@ -78,12 +110,16 @@ export interface PluginHookDecision {
     readonly unreadable: number;
 }
 export declare function decidePluginHooks(input: PluginHookDecisionInput): PluginHookDecision;
-export declare function filterSettingsHookGroups(source: HookSettingsSource, event: string, groups: readonly WireHookGroup[], execFormCapable: boolean, hostFires: boolean, failLoudMcpTool: boolean): SettingsHookFilterResult;
+export declare function filterSettingsHookGroups(source: HookSettingsSource, event: string, groups: readonly WireHookGroup[], execFormCapable: boolean, shellRunsType: (type: string | undefined) => boolean, failLoudMcpTool: boolean, judge?: SettingsHookJudge): SettingsHookFilterResult;
 export interface SettingsHookFilterResult {
     readonly groups: WireHookGroup[];
     readonly drops: SettingsHookDrop[];
     readonly stripped: number;
+    readonly verdicts: SettingsHookVerdict[];
+    readonly excluded: SettingsHookExclusion[];
 }
+export type SettingsHookJudge = (event: string, group: WireHookGroup, entry: WireHookEntry) => HookExecutor;
+export declare function createSettingsHookJudge(engine: HooksWireEngineFacts, shellRuns: ShellRunsHook, promptAuthoredByUser: boolean): SettingsHookJudge;
 export interface SourcedSettingsHookGroup {
     readonly source: HookSettingsSource;
     readonly group: WireHookGroup;
@@ -94,6 +130,12 @@ export interface SettingsHookDedupResult {
     readonly removed: number;
 }
 export declare function pluginHookVerdictOf(plan: HooksWirePlan, pluginId: string, event: string, groupIndex: number, hookIndex: number): PluginHookVerdict | undefined;
+export declare function settingsHooksKeptLocally<T>(plan: HooksWirePlan, event: string, group: {
+    readonly matcher?: string;
+    readonly hooks: readonly T[];
+}, opts?: {
+    readonly engineCompaction?: 'performed' | 'not_performed';
+}): readonly T[];
 export declare function pluginHookReasonText(reason: PluginHookReason): string;
 export declare function settingsHookDropText(reason: SettingsHookDropReason): string;
 export declare function pluginHookExecutorLabel(v: PluginHookVerdict): string;