@sema-agent/core/dist/core/tool-name-readings.d.ts

Stateless, task-oriented AI agent core

/**
 * The ONE table of how every per-call site keyed on an engine tool name reads a call's names, and the read ports a
 * site must go through. A call answers to several names once a caller tool declares aliases (the model's spelling,
 * the wire name the gate resolves it to, the other aliases that resolve to the same row); which of them a site reads
 * is a property of the SITE, declared here once:
 *
 *  · `any`      — a TIGHTEN keyed on an engine name set, or a rule name a user wrote: the call is held under EVERY name it
 *                 answers to ({@link heldBy}); a set-valued table is read as the union of its entries ({@link heldValues}).
 *  · `seat`     — a multi-key seat keyed on engine names: ONE name is chosen ({@link seatOf}) and every key of the seat is
 *                 read under it. `tier` = the name whose irreversibility tier is strictest (`never < maybe < always`, an
 *                 absent tier lowest, ties to the earlier name of the call); `member` = the first name the table holds.
 *  · `wire`     — a GRANT or a ROUTING keyed on an engine name: the call's wire name only ({@link wireOf}).
 *  · `spelling` — a record of what the model said (stream frames, transcripts, counters): the harness event's own name;
 *                 no port — listed so the table is complete.
 *
 * A site passes its {@link SiteId}; the port's parameter type admits only the ids of its kind, so moving a row to another
 * kind fails to compile at the site. `gate:name-readings` holds the rest: a name-keyed table read outside a port, a call's
 * name compared with an engine name outside {@link wireOf}, and a site id spelled at more than one place.
 *
 * Layer-0 vocabulary: depends on nothing but the tool declaration's tier type and, type-only, the mark-source word
 * (`ToolMarkSource`); nothing here runs at import time.
 */
import type { ToolSpec } from "./tool-spec.js";
export type NameReading = {
    readonly kind: "any";
    readonly file: string;
} | {
    readonly kind: "wire";
    readonly file: string;
} | {
    readonly kind: "spelling";
    readonly file: string;
} | {
    readonly kind: "seat";
    readonly rank: "tier" | "member";
    readonly file: string;
};
export declare const NAME_READINGS: {
    readonly "gate.compliance": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "gate.egress": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "gate.peerMessage": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "gate.markSources": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "gate.shellSeat": {
        readonly kind: "seat";
        readonly rank: "tier";
        readonly file: string;
    };
    readonly "gate.sandboxBoundary.egress": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "gate.sandboxBoundary.hand": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "gate.preToolUse": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "gate.askFace": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "fold.readStation": {
        readonly kind: "seat";
        readonly rank: "member";
        readonly file: string;
    };
    readonly "lanes.contentQuestionClass": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "lanes.readOnlyShellAllow": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "lanes.modeFileCommand": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "lanes.contentAskRoute": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "lanes.orgContentAskExemption": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "lanes.persistedEditSkip": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "lanes.persistedLaneSkip": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "lanes.allowLayerQuestionSkip": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "lanes.sandboxQuestionSkip": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "policy.nameLists": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "policy.shellToolsList": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "policy.projectionReplay": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "policy.sessionRules.effect": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "allowEntry.names": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "skillGrant.binding": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "gate.skillActivationSeat": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "policy.permissionRules": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "policy.persistedGrammar": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "policy.durableQuestion": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "policy.sensitivePathGuardedByName": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "floor.protectivePathTarget": {
        readonly kind: "seat";
        readonly rank: "member";
        readonly file: string;
    };
    readonly "mode.planRosterRow": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "offer.laneTool": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "offer.orgQuestionExemption": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "offer.marks": {
        readonly kind: "seat";
        readonly rank: "tier";
        readonly file: string;
    };
    readonly "offer.marks.egress": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "park.riskDescriptor": {
        readonly kind: "seat";
        readonly rank: "tier";
        readonly file: string;
    };
    readonly "report.riskAxes": {
        readonly kind: "seat";
        readonly rank: "tier";
        readonly file: string;
    };
    readonly "report.riskAxes.egress": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "report.riskAxes.negatives": {
        readonly kind: "seat";
        readonly rank: "member";
        readonly file: string;
    };
    readonly "report.markSources": {
        readonly kind: "any";
        readonly file: string;
    };
    readonly "verify.wroteThisRun": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "verify.wroteThisRunSeed": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "event.toolStartEnd": {
        readonly kind: "spelling";
        readonly file: string;
    };
    readonly "hook.postToolUse": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "hook.postToolUseFailure": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "hook.postToolBatch": {
        readonly kind: "spelling";
        readonly file: string;
    };
    readonly "stats.subagentToolCounter": {
        readonly kind: "spelling";
        readonly file: string;
    };
    readonly "activity.sink": {
        readonly kind: "spelling";
        readonly file: string;
    };
    readonly "reconcile.orphanEffect": {
        readonly kind: "spelling";
        readonly file: string;
    };
    readonly "inherited.questionFloat": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "inherited.askFace": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "card.reserved": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "resume.editRecheckQuestionSkip": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "resume.questionArgsShown": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "budget.exemptResult": {
        readonly kind: "wire";
        readonly file: string;
    };
    readonly "compaction.compactableResult": {
        readonly kind: "wire";
        readonly file: string;
    };
};
type Readings = typeof NAME_READINGS;
export type SiteId = keyof Readings;
export type AnySite = {
    [K in SiteId]: Readings[K]["kind"] extends "any" ? K : never;
}[SiteId];
export type WireSite = {
    [K in SiteId]: Readings[K]["kind"] extends "wire" ? K : never;
}[SiteId];
export type SpellingSite = {
    [K in SiteId]: Readings[K]["kind"] extends "spelling" ? K : never;
}[SiteId];
export type TierSeatSite = {
    [K in SiteId]: Readings[K] extends {
        kind: "seat";
        rank: "tier";
    } ? K : never;
}[SiteId];
export type MemberSeatSite = {
    [K in SiteId]: Readings[K] extends {
        kind: "seat";
        rank: "member";
    } ? K : never;
}[SiteId];
export type SeatSite = TierSeatSite | MemberSeatSite;
/** A call as a site reads it: the wire name and, on a gated request, the face whose `names` lists every name it answers to. */
export interface NamedCall {
    readonly toolName: string;
    readonly face?: {
        readonly names?: readonly string[];
    } | undefined;
}
/**
 * Every name the call answers to — the face's `names` when they include the call's name, else the call's name alone (a
 * bare request, or a face minted for another name). A tool-name rule a host matches reaches the call iff its name is on
 * this list; inside the engine only the ports below read it.
 */
export declare function ruleNamesOf(call: NamedCall): readonly string[];
/** An `any` site's membership read: does `set` hold any of the call's names? */
export declare function heldBy(site: AnySite, set: {
    has(name: string): boolean;
}, call: NamedCall): boolean;
/** An `any` site's value read: every entry `map` holds under any of the call's names, in the call's name order. */
export declare function heldValues<V>(site: AnySite, map: {
    get(name: string): V | undefined;
}, call: NamedCall): V[];
/** A `wire` site's read: the call's wire name. */
export declare function wireOf(site: WireSite, call: {
    readonly toolName: string;
}): string;
/** A tool's irreversibility tier, the one vocabulary `ToolSpec.irreversibility` declares. */
type IrreversibilityTierWord = NonNullable<ToolSpec["irreversibility"]>;
/** One seat, read under ONE name: the name the port chose, the value it holds there, and the seat's other keys under that name. */
export interface Seat<V> {
    readonly name: string;
    readonly value: V;
    /** Another key of this seat, read under the seat's name. */
    read<W>(table: {
        get(name: string): W | undefined;
    }): W | undefined;
    /** Another key of this seat, a membership, read under the seat's name. */
    holds(set: {
        has(name: string): boolean;
    }): boolean;
}
/** A tier seat: the risk seat of the engine's irreversibility tables. */
export interface TierSeat extends Seat<IrreversibilityTierWord> {
    /**
     * The seat's shell-seat provenance: the seat's name is in `shellGated` (the engine's shell seat is the sole positive
     * source of its tier) AND no name the call answers to carries a deployment mark in `markSources` — a mark on any of the
     * call's names outranks the shell seat's attribution.
     */
    shellGated(shellGated: {
        has(name: string): boolean;
    }, markSources: {
        get(name: string): ReadonlySet<string> | undefined;
    }): boolean;
}
/**
 * A `seat` site's read. A `tier` seat takes the irreversibility tier table and picks the name whose tier is strictest;
 * a `member` seat takes a table (a map, or a set whose value reads `true`) and picks the first name it holds.
 */
export declare function seatOf(site: TierSeatSite, tiers: {
    get(name: string): IrreversibilityTierWord | undefined;
}, call: NamedCall): TierSeat | undefined;
export declare function seatOf<V>(site: MemberSeatSite, table: {
    get(name: string): V | undefined;
}, call: NamedCall): Seat<V> | undefined;
export declare function seatOf(site: MemberSeatSite, table: {
    has(name: string): boolean;
}, call: NamedCall): Seat<true> | undefined;
export declare function seatOf<V>(site: MemberSeatSite, table: {
    get(name: string): V | undefined;
} | {
    has(name: string): boolean;
}, call: NamedCall): Seat<V | true> | undefined;
export {};