@sema-agent/client-core 0.90.0 → 0.91.0

package/dist/permissionRuleIssue.d.ts

@@ -1,3 +1,3 @@
 export declare const PERMISSION_RULE_ISSUE_CODES: readonly string[];
 export declare const RETIRED_PERMISSION_RULE_ISSUE_CODES: readonly string[];
-export declare function permissionRuleIssueDetail(code: unknown, message: unknown): string;
+export declare function permissionRuleIssueDetail(code: unknown, message: unknown, rule?: string): string;

package/dist/permissionRuleIssue.js

@@ -21,7 +21,7 @@ const ISSUE_MESSAGE_MAX = 200;
 const ISSUE_SENTENCES = Object.freeze({
     'invalid.empty_tool': 'this rule is invalid: it names no tool',
     'invalid.paren': 'this rule is invalid: its parentheses do not parse (escape a literal one as \\( or \\))',
-    'invalid.param_split': 'this rule is invalid: the part before the colon is not a parameter name',
+    'invalid.param_split': 'this rule is invalid: its parentheses do not hold a parameter rule written name:pattern',
     'invalid.allow_param_rule': 'this rule is invalid: an allow rule cannot carry a parameter pattern — only bare tool rules auto-allow',
     'invalid.primary_field': "this rule is invalid: it patterns the tool's primary field, which matches the whole trimmed string rather than a prefix",
     'invalid.cap_exceeded': 'this rule set is invalid: it is over one of the deployment caps (rule count, rule length, pattern length, or star count)',
@@ -35,8 +35,27 @@ const ISSUE_SENTENCES = Object.freeze({
     'unsupported.mcp_paren': 'a parenthesised parameter rule is not supported on an MCP tool name',
     'unsupported.covering_paren': 'a parenthesised parameter rule is not supported on a covering protocol name — the parameter grammar is keyed by an exact tool name, so no mounted tool could ever bear it',
 });
-export function permissionRuleIssueDetail(code, message) {
-    const known = typeof code === 'string' && Object.hasOwn(ISSUE_SENTENCES, code) ? ISSUE_SENTENCES[code] : undefined;
+const PARAM_SPLIT_WITH_COLON = 'this rule is invalid: a parameter rule is written name:pattern, and the name before the colon or the pattern after it is empty';
+const PARAM_SPLIT_NO_COLON = 'this rule is invalid: there is no colon inside the parentheses, so this is not a parameter rule (a parameter rule is written name:pattern)';
+function colonInsideParens(rule) {
+    if (typeof rule !== 'string')
+        return undefined;
+    for (let i = 0; i < rule.length; i += 1) {
+        const ch = rule[i];
+        if (ch === '\\') {
+            i += 1;
+            continue;
+        }
+        if (ch === '(')
+            return rule.indexOf(':', i + 1) !== -1;
+    }
+    return undefined;
+}
+export function permissionRuleIssueDetail(code, message, rule) {
+    const colon = code === 'invalid.param_split' ? colonInsideParens(rule) : undefined;
+    const known = colon !== undefined
+        ? colon ? PARAM_SPLIT_WITH_COLON : PARAM_SPLIT_NO_COLON
+        : typeof code === 'string' && Object.hasOwn(ISSUE_SENTENCES, code) ? ISSUE_SENTENCES[code] : undefined;
     const text = typeof message === 'string' && message.length > 0
         ? capForDisplay(message, ISSUE_MESSAGE_MAX)
         : '';

package/dist/permissionsAllowGrantCapability.d.ts

@@ -12,6 +12,7 @@ export declare function noteEngineCapsForPermissionsAllowGrant(baseUrl: string,
 }): void;
 export declare function observedPermissionsAllowGrant(baseUrl?: string | undefined): PermissionsAllowGrantReading;
 export declare function permissionsAllowGrantAvailable(reading: PermissionsAllowGrantReading): boolean;
-export declare function permissionsAllowGrantDoctorDetail(reading: PermissionsAllowGrantReading): string;
+export declare function allowRulesGate(reading: PermissionsAllowGrantReading, settingsRead: 'clean' | 'partial' | 'unreadable' | undefined): 'open' | 'capability_off' | 'settings_read_not_clean';
+export declare function permissionsAllowGrantDoctorDetail(reading: PermissionsAllowGrantReading, settingsRead?: 'clean' | 'partial' | 'unreadable'): string;
 export declare function forgetPermissionsAllowGrantReading(baseUrl: string | undefined): void;
 export declare function __resetPermissionsAllowGrantReadingsForTests(): void;

package/dist/permissionsAllowGrantCapability.js

@@ -44,6 +44,11 @@ export function permissionsAllowGrantAvailable(reading) {
         return false;
     }
 }
+export function allowRulesGate(reading, settingsRead) {
+    if (!permissionsAllowGrantAvailable(reading))
+        return 'capability_off';
+    return settingsRead === 'clean' ? 'open' : 'settings_read_not_clean';
+}
 function ownReadingField(reading, key) {
     try {
         if (reading === null || typeof reading !== 'object' || Array.isArray(reading))
@@ -54,10 +59,14 @@ function ownReadingField(reading, key) {
         return undefined;
     }
 }
-export function permissionsAllowGrantDoctorDetail(reading) {
-    if (permissionsAllowGrantAvailable(reading)) {
+export function permissionsAllowGrantDoctorDetail(reading, settingsRead) {
+    const gate = allowRulesGate(reading, settingsRead);
+    if (gate === 'open') {
         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';
     }
+    if (gate === 'settings_read_not_clean') {
+        return 'allow rules from settings files kept on this side — this engine reads allow rules as rules, but the settings read that produced them was not reported clean (a settings file was unreadable or had a problem, or no read health was given), so they are not sent; command-line and session allow rules are still sent, and matching approvals are still answered here';
+    }
     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';

package/dist/permissionsDeclaration.d.ts

@@ -12,6 +12,7 @@ export interface PermissionsDeclarationInput {
     readonly allow: readonly string[];
     readonly origins?: WireRuleOrigins;
     readonly cliDeny?: readonly string[];
+    readonly settingsRead: 'clean' | 'partial' | 'unreadable';
 }
 export interface PermissionsDeclarationBuckets {
     deny?: string[];
@@ -21,5 +22,27 @@ export interface PermissionsDeclarationBuckets {
 export interface PermissionsDeclaration {
     permissions?: PermissionsDeclarationBuckets;
 }
+export declare const PERMISSIONS_KEPT_REASONS: readonly ["allow_capability_off", "settings_read_not_clean", "empty_rule", "paren_in_tool_name", "retired_tool_name", "unprefixed_namespaced_name", "incomplete_protocol_name", "home_relative_path", "compile_refused", "content_form_not_grantable", "judge_failed", "duplicate"];
+export type PermissionsKeptReason = (typeof PERMISSIONS_KEPT_REASONS)[number];
+export interface PermissionsKeptRule {
+    rule: string;
+    bucket: 'deny' | 'ask' | 'allow';
+    reason: PermissionsKeptReason;
+}
+export interface PermissionsRewrittenRule {
+    from: string;
+    to: string;
+    bucket: 'deny' | 'ask' | 'allow';
+}
+export interface PermissionsUncheckedRule {
+    rule: string;
+    bucket: 'deny' | 'ask';
+}
+export interface PermissionsDeclarationReport extends PermissionsDeclaration {
+    kept: PermissionsKeptRule[];
+    rewritten: PermissionsRewrittenRule[];
+    unchecked: PermissionsUncheckedRule[];
+}
 export declare function permissionsDeclaration(input: PermissionsDeclarationInput, caps: PermissionsAllowGrantReading): PermissionsDeclaration;
+export declare function permissionsDeclarationReport(input: PermissionsDeclarationInput, caps: PermissionsAllowGrantReading): PermissionsDeclarationReport;
 export {};

package/dist/permissionsDeclaration.js

@@ -1,5 +1,5 @@
 import { hasCoreValuePort, protocolOf, retiredToolNames, ruleToolGrammarOf, validatePermissionRules } from './coreValuePorts.js';
-import { permissionsAllowGrantAvailable } from './permissionsAllowGrantCapability.js';
+import { allowRulesGate } from './permissionsAllowGrantCapability.js';
 const RULE_TRUST_ORDER = [
     'policySettings',
     'cliArg',
@@ -9,6 +9,20 @@ const RULE_TRUST_ORDER = [
     'localSettings',
     'projectSettings',
 ];
+export const PERMISSIONS_KEPT_REASONS = Object.freeze([
+    'allow_capability_off',
+    'settings_read_not_clean',
+    'empty_rule',
+    'paren_in_tool_name',
+    'retired_tool_name',
+    'unprefixed_namespaced_name',
+    'incomplete_protocol_name',
+    'home_relative_path',
+    'compile_refused',
+    'content_form_not_grantable',
+    'judge_failed',
+    'duplicate',
+]);
 function normalizeLegacyToolName(name) {
     switch (name) {
         case 'Task':
@@ -61,15 +75,15 @@ function requireRulePorts() {
     throw new Error(`permissionsDeclaration: 规则判据端口缺席(${missing.join(' / ')})—— 先用 installCoreValuePorts 装上 core 的同名实现。` +
         '缺席不等于全部合格:不判就发会让整份请求被引擎拒收,不判就删会静默丢掉 deny 规则,所以这里拒绝装配。');
 }
-function engineWireSafe(name) {
+function wireIssue(name) {
     if (name.includes('('))
-        return false;
+        return 'paren_in_tool_name';
     if (retiredToolNames().has(name))
-        return false;
+        return 'retired_tool_name';
     const ns = protocolOf(name);
     if (ns === undefined)
-        return !name.includes('__');
-    return ns.parse(name) !== undefined;
+        return name.includes('__') ? 'unprefixed_namespaced_name' : undefined;
+    return ns.parse(name) !== undefined ? undefined : 'incomplete_protocol_name';
 }
 function wholeServerRuleName(name) {
     const read = name.trim();
@@ -91,12 +105,12 @@ function compileVerdict(rule, behavior) {
         return 'unknown';
     }
 }
-function wireSubset(rules, behavior) {
-    const out = new Set();
+const kept = (reason) => ({ sent: false, reason });
+function judgeList(rules, behavior) {
     let portsChecked = false;
-    for (const rule of rules) {
-        if (typeof rule !== 'string' || rule === '')
-            continue;
+    return rules.map((rule) => {
+        if (rule === '')
+            return kept('empty_rule');
         if (!portsChecked) {
             requireRulePorts();
             portsChecked = true;
@@ -104,50 +118,78 @@ function wireSubset(rules, behavior) {
         const parsed = parseRule(rule);
         if (parsed.ruleContent === undefined) {
             const name = wholeServerRuleName(parsed.toolName);
-            if (!engineWireSafe(name))
-                continue;
-            if (out.has(name))
-                continue;
+            const issue = wireIssue(name);
+            if (issue !== undefined)
+                return kept(issue);
             const verdict = compileVerdict(name, behavior);
-            if (verdict === 'refused' || (verdict === 'unknown' && behavior === 'allow'))
-                continue;
-            out.add(name);
-            continue;
+            if (verdict === 'refused')
+                return kept('compile_refused');
+            if (verdict === 'unknown' && behavior === 'allow')
+                return kept('judge_failed');
+            return { sent: true, wire: name, unchecked: verdict === 'unknown' };
         }
-        if (!engineWireSafe(parsed.toolName))
-            continue;
+        const issue = wireIssue(parsed.toolName);
+        if (issue !== undefined)
+            return kept(issue);
         if (ruleToolGrammarOf(parsed.toolName) === 'path' && parsed.ruleContent.startsWith('~/'))
-            continue;
+            return kept('home_relative_path');
         const verdict = compileVerdict(rule, behavior);
-        if (verdict === 'compiles' || (verdict === 'unknown' && behavior !== 'allow'))
-            out.add(rule);
-    }
-    return [...out];
+        if (verdict === 'refused')
+            return kept(behavior === 'allow' ? 'content_form_not_grantable' : 'compile_refused');
+        if (verdict === 'unknown' && behavior === 'allow')
+            return kept('judge_failed');
+        return { sent: true, wire: rule, unchecked: verdict === 'unknown' };
+    });
 }
-function projectBucketByTrust(raw, behavior, originOf, cliRules) {
-    const present = new Set(raw);
+function outsideSettingsFiles(origin) {
+    return origin === 'cliArg' || origin === 'session';
+}
+function judgeBucket(raw, behavior, originOf, cli, settingsGate) {
+    const firstSlot = new Map();
+    for (const s of raw)
+        if (!firstSlot.has(s.rule))
+            firstSlot.set(s.rule, s);
     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))
+            if (rank >= 0 && typeof r === 'string' && firstSlot.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);
+    const unknownOrigin = [...firstSlot.keys()].filter((r) => originOf === undefined || rankOf(originOf.get(r)) < 0);
+    const fateOfRule = new Map();
+    const sent = [];
+    const winnerOf = new Map();
+    const cliFates = cli === undefined ? [] : [...cli.fates];
+    const place = (slot, fate) => {
+        if (!fate.sent)
+            return fate;
+        if (winnerOf.has(fate.wire))
+            return kept('duplicate');
+        winnerOf.set(fate.wire, slot);
+        sent.push(fate.wire);
+        return fate;
+    };
+    const appendGroup = (group, origin) => {
+        const held = settingsGate !== undefined && !outsideSettingsFiles(origin);
+        const fates = held ? group.map(() => kept(settingsGate)) : judgeList(group, behavior);
+        group.forEach((r, k) => fateOfRule.set(r, place(firstSlot.get(r), fates[k])));
     };
     RULE_TRUST_ORDER.forEach((origin, rank) => {
-        if (origin === 'cliArg')
-            append(cliRules);
-        append(wireSubset(groups[rank], behavior));
+        if (origin === 'cliArg' && cli !== undefined)
+            cli.slots.forEach((s, k) => (cliFates[k] = place(s, cliFates[k])));
+        appendGroup(groups[rank], origin);
     });
-    append(wireSubset(unknownOrigin, behavior));
-    return [...out];
+    appendGroup(unknownOrigin, undefined);
+    const fates = raw.map((s) => {
+        const f = fateOfRule.get(s.rule);
+        if (firstSlot.get(s.rule) === s)
+            return f;
+        return f.sent || f.reason === 'duplicate' ? kept('duplicate') : f;
+    });
+    return { sent, fates: [...fates, ...cliFates], winnerOf };
 }
 const WHO = 'permissionsDeclaration';
 function ownField(obj, key, where) {
@@ -192,7 +234,8 @@ function originMap(v, key) {
     }
     return snap;
 }
-export function permissionsDeclaration(input, caps) {
+const slotsOf = (list, name) => (list ?? []).map((rule, at) => ({ rule, list: name, at }));
+function assemble(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}`}。`);
     }
@@ -211,17 +254,54 @@ export function permissionsDeclaration(input, caps) {
         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 } : {};
+    const gate = allowRulesGate(caps, ownField(input, 'settingsRead', ''));
+    const cliSlots = slotsOf(cliDeny, 'cliDeny');
+    const cli = cliDeny === undefined ? undefined : { slots: cliSlots, fates: judgeList(cliDeny, 'deny') };
+    const denySlots = slotsOf(deny, 'deny');
+    const askSlots = slotsOf(ask, 'ask');
+    const allowSlots = slotsOf(allow, 'allow');
+    const denyJ = judgeBucket(denySlots, 'deny', origins.deny, cli);
+    const askJ = judgeBucket(askSlots, 'ask', origins.ask, undefined);
+    const allowJ = gate === 'capability_off'
+        ? { sent: [], fates: allowSlots.map(() => kept('allow_capability_off')), winnerOf: new Map() }
+        : judgeBucket(allowSlots, 'allow', origins.allow, undefined, gate === 'settings_read_not_clean' ? 'settings_read_not_clean' : undefined);
+    const buckets = {};
+    if (denyJ.sent.length > 0)
+        buckets.deny = [...denyJ.sent];
+    if (askJ.sent.length > 0)
+        buckets.ask = [...askJ.sent];
+    if (allowJ.sent.length > 0)
+        buckets.allow = [...allowJ.sent];
+    const keptRows = [];
+    const rewritten = [];
+    const unchecked = [];
+    const rows = [
+        ['deny', [...denySlots, ...cliSlots], denyJ],
+        ['ask', askSlots, askJ],
+        ['allow', allowSlots, allowJ],
+    ];
+    for (const [bucket, slots, j] of rows) {
+        slots.forEach((s, k) => {
+            const f = j.fates[k];
+            if (!f.sent)
+                keptRows.push({ rule: s.rule, bucket, reason: f.reason });
+        });
+        for (const wire of j.sent) {
+            const winner = j.winnerOf.get(wire);
+            if (winner.rule !== wire)
+                rewritten.push({ from: winner.rule, to: wire, bucket });
+            const f = (winner.list === 'cliDeny' ? j.fates[denySlots.length + winner.at] : j.fates[winner.at]);
+            if (f.sent && f.unchecked && bucket !== 'allow')
+                unchecked.push({ rule: wire, bucket });
+        }
+    }
+    return { buckets, report: { kept: keptRows, rewritten, unchecked } };
+}
+export function permissionsDeclaration(input, caps) {
+    const { buckets } = assemble(input, caps);
+    return Object.keys(buckets).length > 0 ? { permissions: buckets } : {};
+}
+export function permissionsDeclarationReport(input, caps) {
+    const { buckets, report } = assemble(input, caps);
+    return { ...(Object.keys(buckets).length > 0 ? { permissions: buckets } : {}), ...report };
 }

package/dist/promptDelivery.d.ts

@@ -1,16 +1,24 @@
 import type { AgentEvent } from '@sema-agent/sdk';
 import { type SelfHealOutcome } from './adapter/activeRunSelfHeal.js';
+import type { HumanTurnDelivered } from './humanTurn.js';
 export interface PromptDeliveryRecord {
     readonly u: string;
     readonly s: 'a' | 'd';
+    readonly by?: 'frame' | 'steer_receipt';
+    readonly share?: 'full' | 'partial';
 }
 export interface PromptDeliveryLedger {
-    attempted(batchUuids: readonly string[]): readonly PromptDeliveryRecord[];
-    deliveredByFrame(batchUuids: readonly string[], event: AgentEvent): readonly PromptDeliveryRecord[];
-    deliveredBySteerReceipt(batchUuids: readonly string[], outcome: SelfHealOutcome): readonly PromptDeliveryRecord[];
+    attempted(batchUuids: readonly string[], opts?: {
+        readonly generation?: number;
+    }): readonly PromptDeliveryRecord[];
+    deliveredByFrame(batchUuids: readonly string[] | HumanTurnDelivered, event: AgentEvent): readonly PromptDeliveryRecord[];
+    deliveredBySteerReceipt(batchUuids: readonly string[] | HumanTurnDelivered, outcome: SelfHealOutcome): readonly PromptDeliveryRecord[];
     isAttempted(uuid: string): boolean;
     isDelivered(uuid: string): boolean;
     knownUndelivered(uuid: string): boolean;
+    deliveryShareOf(uuid: string): 'full' | 'partial' | undefined;
+    undeliveredInGeneration(generation: number): readonly string[];
+    droppedKeyCount(): number;
     batchOf(uuid: string): readonly string[] | undefined;
     toRecords(): readonly PromptDeliveryRecord[];
     fromRecords(records: readonly PromptDeliveryRecord[]): readonly PromptDeliveryRecord[];