@sema-agent/core
Version:
Stateless, task-oriented AI agent core
677 lines (676 loc) • 47.8 kB
TypeScript
/**
* design/173 — the wiring manifest: a machine-readable disclosure of HOW this deployment/run is
* assembled around the optional human-interaction seams (ask / question / elicit / park lane /
* durability / fleet observability / governance surfaces).
*
* GUARANTEE BOUNDARY (design/173 §0): this is STATIC ASSEMBLY SELF-DISCLOSURE — seam presence and
* shape, as facts. It does NOT prove liveness (a callback bound to the wrong run, a dead queue, an
* adapter's internal failure, an answer routed to the wrong instance). Liveness belongs to
* round-trip probes, which are a separate obligation. Nothing here may claim "the wiring was
* verified" — only "the wiring was disclosed". This module provides no liveness API, deliberately;
* consumers (e.g. a park-wiring startup self-check) must quote this boundary rather than promise
* more than the manifest can know.
*
* TWO HALVES, ONE SCHEMA (design/173 §2.1): the STATIC half ({@link describeStaticWiring}) is a pure
* synchronous function over `(deps, spec)` — a server startup self-check. Facts it cannot compute
* (per-principal runtime caps, the prepare-time safety-tool vocabulary) are reported `"unresolved"`,
* never guessed, and `ask.effective` is OMITTED entirely (reporting "would park" as "auto-deny"
* would be a false fact, worse than silence). The EFFECTIVE half is built once per prepared leg by
* `prepareTask` from RESOLVED facts, through the SAME {@link deriveWiringManifest} derivation — two
* copies of the derivation would drift, so there is exactly one. A startup snapshot and a leg's
* effective snapshot are two DIFFERENT facts; neither may impersonate the other.
*/
import { type PermissionMode } from "./ask-origin.js";
import type { RunnerDeps, TaskSpec } from "./types.js";
import { type StoreDurability } from "./checkpoint-store.js";
import type { WiringManifestHookEntry } from "./hook-seats.js";
import type { McpDelivered, McpFailureKind, McpServerLiveness } from "./mcp-failure.js";
import type { WriteProtectionTargetView } from "./write-protect.js";
export type { StoreDurability };
/** The manifest-face projection of {@link StoreDurability}: `"declared_durable"` (the name says it —
* a DECLARATION relayed, not a verification) vs `"process_local"` (declared so, or fail-closed
* absent). */
export type ManifestDurability = "declared_durable" | "process_local";
/** Which prepare leg an EFFECTIVE manifest describes (`leg` is absent on the static half — a
* startup self-check has no leg). taskId/parentTaskId ride the event's `TaskEventIdentity`, not
* this object (design/173 §8.4). "Every leg self-evidences" means ON ITS OWN STREAM: a delegated
* child's manifest rides the CHILD's event stream and is deliberately not in the parent-forwarding
* whitelist — a host that wants a child's assembly evidence subscribes to the child. */
export type WiringLegKind = "root" | "child" | "resume";
/** The shape of the resolved permission-ask seat (`spec.onAsk ?? deps.onAsk`): a live approver
* callback, a blanket `"allow"`/`"deny"` policy setting, or nothing at all. `"deny"` (a deliberate
* policy) and `"absent"` (a degrade to the headless auto-deny default) are DISTINCT on purpose —
* design/173 */
export type AskSeamForm = "callback" | "allow" | "deny" | "absent";
/** What a policy `ask` actually reaches under this assembly. `"unresolved"` = not computable from
* the facts at hand (the static half's park-dependent arm). */
export type AskEffective = "human_reachable" | "auto_allow" | "auto_deny" | "park_only" | "unresolved";
/**
* The content-question channel, three-valued (design/173 §8.2 — a derived enum, not a bare
* boolean): `"wired"` (a resolved `onQuestion` face exists), `"absent"` (none), or
* `"stripped_bg_lane"` — the ENGINE deliberately stripped the spawn turn's per-request face from a
* leg that outlives the request: a session-scoped background/retained leg, or an agent the Workflow tool
* spawned (submit-and-return) — correct design, not a configuration lie; the flag is minted
* ONLY by the engine's strip sites, pair-produced with the strip itself — never inferred from spec
* shape).
*/
export type QuestionChannelState = "wired" | "absent" | "stripped_bg_lane";
/** Which seat supplied a resolved seam value (`spec` wins over `deps` everywhere). Tree-internal
* child legs read `"spec"` for inherited faces by construction — the delegation lane copies the
* parent's effective face onto the child SPEC seat (design/173 opus F7). */
export type SeamProvenance = "spec" | "deps";
/** Machine-readable reason codes for a park lane that is not (or not provably) effective. */
export type ParkLaneReason = "no_checkpoint_store" | "no_durable_approval_opt_in" | "no_force_durable_gate" | "no_armed_safety_vocabulary" | "await_runtime_caps" | "await_tool_vocabulary";
/**
* The closed set of auto-mode ARMING outcomes a leg's manifest reports
* ({@link WiringManifest.autoMode}). Minted from the arming predicate's own three-arm read, as the
* FIRST failing arm in predicate order:
* - `no_intent` — the declared permission mode is not `auto` (no `permissionMode: "auto"` seat, none
* inherited on the chain / recorded on the resumed checkpoint; a non-auto run).
* - `no_face` — intent, but no `RunnerDeps.autoMode` deployment face (the trust gate).
* - `denied` — intent + face, but the organization's deny bit (`RuntimeCaps.autoMode:false`)
* as the resolver STATED it.
* - `resolver_fault` — intent + face, and the deny bit was COINED by a resolver fault (a throw, or a
* marshalled/non-record result the value screen refused) — an outage, not a
* verdict; the same fail-closed outcome as `denied`, named apart so a consumer
* can tell "policy said no" from "the entitlement source was unreachable".
* - `armed` — all three arms held; the classifier decider was minted for this leg.
*/
export declare const AUTO_MODE_ARM_REASONS: readonly ["armed", "no_intent", "no_face", "denied", "resolver_fault"];
export type AutoModeArmReason = (typeof AUTO_MODE_ARM_REASONS)[number];
/**
* The leg's auto-mode arming FACT as the manifest carries it: `armed ⇔ reason === "armed"`; `deniedSource` (#692 C-d,
* additive) is present only beside a STATED `denied` and names which settings plane's ratchet turned auto mode off
* ({@link import("./runtime-caps.js").AUTO_MODE_DENY_SOURCES}: `org` / `local` / `settings`) — the resolver's
* own word, carried through, never inferred; a `denied` with no source is a resolver that does not track sources,
* and a `resolver_fault` never carries one (the screen strips a source it refused).
*/
export interface AutoModeArmFact {
armed: boolean;
reason: AutoModeArmReason;
deniedSource?: import("./runtime-caps.js").AutoModeDenySource;
}
/**
* One declared MCP server's materialization result for THIS leg — the per-server connection-state
* read face on {@link WiringManifest.mcp}. `status` is the connect-time verdict of this leg's
* materialize (a snapshot, never a heartbeat — the same semantics as `MaterializedMcp.statuses`,
* which it is projected from): `connected` (tools listed; `toolCount` = the mounted roster size after
* intake), `failed` (the connect or the tool listing threw — `errorCode`/`delivered`/`httpStatus` are the
* failure record spread flat (see the MCP failure vocabulary's `McpFailure`), `error` the
* neutralized, length-bounded remote text), `skipped` (declared on the spec but this leg produced no
* status for it — the materialization did not reach it). `source` is the DECLARING side's own label
* (`McpServerSpec.source`: plugin / user / project / local, or anything the deployment writes),
* echoed back so a shell can group servers by where the declaration came from; core reads nothing
* off it. Ordered as declared.
*/
export interface WiringManifestMcpEntry {
name: string;
source?: string;
status: "connected" | "failed" | "skipped";
errorCode?: McpFailureKind;
delivered?: McpDelivered;
httpStatus?: number;
error?: string;
toolCount: number;
/**
* The engine's last liveness OBSERVATION about this server as of this leg's materialize — a per-leg
* snapshot of the record described on `McpServerStatus.liveness`, refreshed when a leg emits its
* manifest and at no other time (the engine runs no probe and adds no traffic of its own to answer
* it, so there is nothing here to poll).
*
* It is NOT `status`: that is the connect-time verdict of the dial ("did this leg mount it"), while
* this is what the connection layer learned about REACH — and the two legitimately disagree, most
* plainly on a server that answered the handshake with a protocol error (`status:"failed"` beside
* `liveness.state:"reachable"`: up, and misconfigured). It is NOT a re-dial's `outcome` either —
* that is one action's judgment, this is a standing observation the action updates.
*
* PRESENT IFF an observation exists. Absent = INDETERMINATE and nothing else: the leg produced no
* attempt record for this declaration (`status:"skipped"`), or the declaration could not be dialed
* at all (`errorCode:"invalid_config"` — a malformed url never reaches a transport), or the manifest
* predates the field. A consumer must not fold absence into `unknown`, into "healthy" or into "off";
* `unknown` is the different and stronger statement that core DID look and could not tell.
*/
liveness?: McpServerLiveness;
}
/** Which LSP lanes this leg armed. The two lanes are INDEPENDENT and the word is their product: `tool` = the
* code-intelligence tool mounted and nothing more; `diagnostics` = the push lane armed (a registry-feeding
* manager, write-capable hands, no opt-out) while the tool is NOT on the roster; `tool_and_diagnostics` =
* both. A leg whose `LSP` tool was excluded can still be pushing diagnostics. */
export declare const LSP_LANES: readonly ["tool", "diagnostics", "tool_and_diagnostics"];
export type LspLane = (typeof LSP_LANES)[number];
/** Why a leg's hand band is NOT mounted ({@link WiringManifest.hands}`.reason`), one word per false branch of the
* hands decision (`prepare-execution-env.ts`); it has one: `no_execution_env` = neither env seat supplied one. A
* literal, not a registered closed set (the gate admits sets of two or more) until a second branch exists. */
export type HandsUnmountedReason = "no_execution_env";
/** The manifest's hands seam from the leg's one hands fact (see {@link WiringManifest.hands}). */
export declare function deriveHandsSeam(handsMounted: boolean): {
mounted: boolean;
reason?: HandsUnmountedReason;
};
/** The contract id the LSP tool mounts under (`createLspTool`) — the roster's structural discriminator, which
* a disclosure keys on instead of re-spelling the wire name. */
export declare const LSP_CONTRACT_ID = "core.lsp@1";
/** The manifest's LSP seam from its two INDEPENDENT facts (see {@link WiringManifest.lsp}): the lane word is
* their product, and is absent only when neither lane is live. */
export declare function deriveLspSeam(mounted: boolean, diagnosticsLive: boolean): {
mounted: boolean;
lane?: LspLane;
};
/**
* design/173 §2.2/§8.4 — the wiring manifest. Consumers MUST ignore unknown fields
* (`schemaVersion` bumps only on a semantic break of an EXISTING field). The TaskEvent face is the
* host/operator plane — the manifest never enters model context.
*/
export type { WiringManifestHookEntry };
export interface WiringManifest {
schemaVersion: 1;
/** Present on EFFECTIVE (per-leg) manifests only; the static half has no leg. */
leg?: {
kind: WiringLegKind;
};
/** Effective half only — the leg's team role ({@link import("../agents/team-role.js").teamRoleOf}):
* `lead` for a top-level leg, `teammate` for a named delegation, `none` for an unnamed one. Leg-local
* (excluded from the fingerprint). */
teamRole?: import("../agents/team-role.js").TeamRole;
/** Effective half only, present iff the spec reported one — the session's self-reported presence,
* the very object `TaskSpec.peerPresence` carried, for a host to copy into the directory row it
* writes without parsing the spec. Leg-local (excluded from the fingerprint). */
peerPresence?: import("../agents/peer-directory.js").PeerPresence;
ask: {
form: AskSeamForm;
/** Absent iff `form === "absent"` (no seat supplied a value — a fabricated provenance would be
* a false fact). */
provenance?: SeamProvenance;
/** OMITTED on the static half (design/173 §8.4): the absent-form arm depends on the park lane,
* which the static half cannot always resolve. Always present on the effective half. */
effective?: AskEffective;
};
question: {
/** Three-valued channel state — see {@link QuestionChannelState}. The field keeps the frozen
* design name `wired`. */
wired: QuestionChannelState;
/** Present iff `wired === "wired"`. */
provenance?: SeamProvenance;
/**
* design/173 §3 (F13, effective half only) — the composition-lie detector:
* `interactiveTools === true` mounted the question tool while NO delivery face exists (no live
* `onQuestion`, no durable park consumer, not an engine-stripped lane). The model will be
* offered a question tool whose answers can reach nobody. Always disclosed here; under
* posture `"interactive"` the prepare door additionally refuses the leg.
*/
interactiveToolsWithoutDeliveryFace?: true;
};
/** The interaction-posture declaration (the prepare door's input): `"interactive"` promises a
* reachable human and the door refuses a leg that cannot deliver one, `"headless"` documents the
* opposite, `"absent"` = no declaration (no check). Until this field existed, posture was the one
* interactive-face declaration the manifest did not report. */
interaction: {
posture: "interactive" | "headless" | "absent";
};
/** `seamWired` = a deployment `onElicit` seam exists. Seam presence ≠ the elicitation family is
* usable: the other half is per-server opt-in (`spec.mcp[].elicitation === true`), counted in
* `serversOptedIn` (statically readable from the spec). */
elicit: {
seamWired: boolean;
serversOptedIn: number;
};
parkLane: {
/** A checkpoint store is wired (capability — design/173: capability and current policy
* are reported separately). */
capable: boolean;
/** capable ∧ (durableApproval opt-in ∨ forceDurableGate entitlement ∨ armed safety-tool
* vocabulary). `"unresolved"` on a static half that cannot decide (runtime caps / tool
* vocabulary are prepare-time facts). */
effective: boolean | "unresolved";
/** Why `effective` is `false`/`"unresolved"` — empty when `true`. The derivation chain an
* operator follows from `static unresolved` to `effective park unavailable`. */
reasons: readonly ParkLaneReason[];
/** design/173 §8.4 (opus R7): the DECLARED durability of the resolved checkpoint store — an
* armed park lane over a process-local store is the "armed but memory-backed" degrade shape
* §1 names, and it must be reportable. Present iff `capable`. */
checkpointDurability?: ManifestDurability;
};
/** The session store's DECLARED durability (declaration relayed verbatim — never class-name
* sniffing; absent declaration reads fail-closed as `process_local`). */
session: {
store: ManifestDurability;
};
/** `subagentTranscripts` — subagent transcript persistence: the deployment-level delegation-
* transcript durability TIER, a pure declaration read ({@link resolveSubagentTranscriptTier}):
* `none` = no agent-row store (pre-151 in-memory lifecycle); `rows` = rows + terminal snapshots
* survive a restart, transcripts follow the session store's fate; `full` = the C18 promise —
* a completed/failed/killed(non-user) subagent minted through the deps-visible assembly is
* continuable across a process restart. A statement about the DEPS-VISIBLE assembly only: a
* caller-mounted Agent tool over its own runner is outside this manifest's sight (per-read
* honest degrade + the integrity notice own that case, never a fabricated tier) — and that
* blind spot is load-bearing here, because the store this field is derived from is the ROOT
* leg's while the store an ordinary child transcript is actually minted through is the AGENT
* TOOL's runner's ({@link resolveSubagentTranscriptTier} names the rule and the fork-lane
* exception). The word names ADDRESSABILITY: `none`/`rows` are silent on whether a child
* transcript reaches disk at all, and only `full` promises the a* handle survives a restart. */
fleet: {
backgroundAgentStore: boolean;
hostChildEventSink: boolean;
subagentTranscripts: SubagentTranscriptTier;
};
/** design/179 — the persisted allow-rule seam. The ONE loosening seam in the assembly, so its presence
* is a fact an operator has to be able to read off the manifest rather than infer. `false` on a
* deployment that wired no store, which is the shape the field has to have: an absent field would say
* "this build has no such feature", and a present-and-false one says "it exists and is off here". */
permissionRules: {
storeWired: boolean;
/** design/182 §9 — this deployment DECLARED that it drives cloud sync for the wired rule store
* (`RunnerDeps.permissionRuleSyncWired`). Connecting a bucket to a sync endpoint merges every
* device, the transport and the server into ONE consent trust domain, which is a fact an operator
* reads off the manifest rather than infers. `false` on a deployment that does not sync — same
* present-and-false shape as `storeWired`, for the same reason. */
syncWired: boolean;
/** design/182 §7 / design/389 — this deployment DECLARED org governance (the store was composed with
* an `org` partition, whose constructor refuses a declaration with no snapshot source). `true` also means
* the fail-closed availability contract is armed: while no org snapshot can be adjudicated
* against, every terminal allow tightens to a real-approval ask. */
orgGoverned: boolean;
};
/**
* Governance surfaces (presence facts only). `audience: "operator"` is the MACHINE-READABLE
* projection classification (design/173): a serving layer forwarding this event to a
* multi-tenant/shared stream MUST project this section for operators only — and when it does no
* projection, the default is to NOT disclose the section, never to leak it.
*/
governance: {
audience: "operator";
lockedConfig: boolean;
compliance: boolean;
memoryAdmission: boolean;
retention: boolean;
};
/**
* EFFECTIVE half only, present iff the model gate trimmed a default-mounted tool from THIS run's
* roster: the per-session READ face of the same fact `config.tool_model_gate_removed` announces on
* the operator sink (one notice per sink, not per session — a client that needs "which default tools
* did MY session lose" reads it here). `class` = the gate class the table keyed the trim on, `removed`
* = the wire names not mounted, `restore` = the three valves in one sentence. Minted from the SAME
* gate decision the notice reads (one source, projected twice); absent = no trim on this run. A gate
* table with several classes trimming at once reports the FIRST class here and every removed name
* across classes in `removed` (the notice keeps its per-class lines).
*/
modelGate?: {
class: string;
removed: readonly string[];
restore: string;
};
/**
* EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest (unlike
* `modelGate`, which is present only when a trim happened: auto mode has an answer on every leg,
* so absence here means an older mint or an external derivation, never "not applicable"). The
* per-leg READ face of the auto-mode arming decision: `armed` ⇔ `reason === "armed"` (the
* classifier decider was minted for this leg), and `reason` names the first arm that failed
* otherwise — see {@link AUTO_MODE_ARM_REASONS}. A serving layer that used to infer the mode from
* spec shape reads it here instead. The classifier's availability is a per-CALL fact (an unavailable
* round goes on to the approval seat or is refused with a sentence that says so, and the next round is
* classified afresh), so there is no session-level
* breaker face here and nothing about availability enters {@link configFingerprint}.
*/
autoMode?: AutoModeArmFact;
/**
* EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest (the `autoMode`
* posture: every leg has an answer — an empty array is "this leg declared no servers", absence is
* an older mint or an external derivation). The per-server MCP connection-state read face: one
* {@link WiringManifestMcpEntry} per server the leg's frozen spec declared, in declaration order,
* projected from THIS leg's materialization (`MaterializedMcp.statuses`) — a connect-time snapshot
* of "did this leg connect", never a live health signal. A shell that shows per-server state
* (connected / failed with a cause a person can act on / tool counts, grouped by declaring
* `source`) reads it here instead of inferring from the roster or the failure notices. NOT part of
* {@link configFingerprint}: connection state is a fact about this leg's attempt, not about the
* assembly, and legs of one assembly must fingerprint alike whether or not a server was up.
*/
mcp?: readonly WiringManifestMcpEntry[];
/**
* design/388 §2.5 — EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest:
* the leg's TOOL ROSTER — one row per mounted instance in wire order, every declared axis, the
* engine-minted identity (`capabilityId`), the schema-derived `inputKeys` / rule vocabulary and the
* roster `digest`. The static half has no roster to report (it mounts nothing). NOT part of
* {@link configFingerprint}: a roster is per-leg by construction (a child leg mounts a different set
* under the same assembly), so hashing it would break the cross-leg equality the fingerprint
* advertises — the roster carries its own digest for that. A run-time change to the set arrives as a
* `tool_roster_delta` event, never as a re-emitted manifest.
*/
tools?: import("./tool-roster.js").ToolRoster;
/**
* EFFECTIVE half only: the hook seats this leg wired, one entry per family, in {@link import("./hook-seats.js").HOOK_FAMILIES} order. PRESENT IFF at least one
* seat is wired — a deployment that wires none reports nothing here and its manifest (and {@link configFingerprint}) is byte-for-byte what it was; an empty
* array is never emitted, so absence reads as "this leg wired no hook RECORD of its own" — NOT as "no hook runs": a delegated child with no local record can
* still be screened (and refused) by an ancestor's `preToolUse` through the gate's constraint fold, which this face deliberately does not call a hook of
* this leg. Every entry is deployment code the engine awaits on the critical path, fail-closed on the two decision seats. EXCLUDED from
* {@link configFingerprint}: the record is a per-task seat, so one assembly's legs legitimately differ on it.
*/
hooks?: readonly WiringManifestHookEntry[];
/**
* EFFECTIVE half only: the LSP code-intelligence seam. PRESENT IFF a manager seat resolved
* (`spec.lspManager ?? deps.lspManager`); a deployment that wires none reports nothing (byte-for-byte
* unchanged, fingerprint included). `mounted` is the ROSTER fact, not the seat fact — a wired manager
* whose `LSP` tool was excluded reports `false` — and `lane` is INDEPENDENT of it: the diagnostics push
* lane arms on the manager, the hands and the opt-out, never on the mount, so
* `{mounted:false, lane:"diagnostics"}` is a real and reachable state. `lane` is absent only when
* neither lane is live.
*/
lsp?: {
mounted: boolean;
lane?: LspLane;
};
/**
* EFFECTIVE half only, ALWAYS present on an engine-minted effective manifest: is this leg's HAND band (the file
* tools, and the shell tools where the env has a shell) mounted — the value the band's mount reads, stated
* positively instead of inferred from `tools[]` or the write-protection word. `true` ⇔ the factory minted an env
* or the static `executionEnv` seat is not `undefined` (a JS caller's `null` and a `StubExecutionEnv` count: the
* band mounts over them, without a shell); `false` carries `reason` ({@link HandsUnmountedReason}), which is absent
* beside `true`. Whether a full shell is reachable is `tools[]`'s fact. ABSENT = an older mint or an external
* derivation, never a state. IN {@link configFingerprint}: an ASSEMBLY fact (the {@link writeProtection} class).
*/
hands?: {
mounted: boolean;
reason?: HandsUnmountedReason;
};
/**
* EFFECTIVE half only, ALWAYS present on an engine-minted effective manifest: the leg's PERMISSION MODE as the engine
* resolved it — `requested` (the caller's word; absent = declared nothing), `effective` (the mode the leg runs under:
* the request clamped under a parent's ceiling, then folded to `default` where the deployment denies it or the
* classifier face is absent), `foldedBy` (present iff the two differ: `operator_deny` / `face_absent` /
* `inherited_ceiling`). The same three members answer every steer of the mode (`TaskStream.setPermissionMode`) and
* ride the fold notice's detail. A shell renders its mode indicator from `effective`, never from what it sent.
* ABSENT = an older mint, never a state. Leg-local (excluded from {@link configFingerprint}: a child clamped under its
* parent legitimately differs from it).
*/
permissionMode?: import("./mode-policy.js").PermissionModeReceipt;
/**
* EFFECTIVE half only, PRESENT IFF this leg compiled a write-protection judge — a deployment that
* replaced the table with `[]` opted the layer out entirely, and reports nothing here rather than a
* judge-shaped word about a judge that does not exist (absence = "no judge on this leg", which is a
* different fact from either value below, and strictly weaker than both).
*
* `targetView` is the JUDGE'S OWN word (`WriteProtectionMatcher.targetView`, relayed verbatim), and it
* is how an operator tells a hands-less deployment's write floor from a hands-ful one without inspecting
* the engine's seats — the same fact `config.write_protection_target_view_absent` announces once per run
* when a covered write tool is mounted beside a `"spelling-only"` judge.
*
* IN the fingerprint below (unlike `tools`/`lsp`/`hooks`): which view the judge got is an ASSEMBLY fact
* — it follows the table seat and whether the deployment wired hands at all — so legs of one assembly
* agree on it, which is exactly the equality the fingerprint advertises.
*
* @contract write_protection.target_view_disclosed — WHICH reading of a write's target the leg's
* write-protection judge holds is DISCLOSED, never inferred: the judge self-reports one of two words at
* its compile (`"target"` — it holds an execution environment and re-judges a table-missing spelling on
* its resolved real target; `"spelling-only"` — it holds none, so the spelling is the whole judgment and
* an alias onto a protected path is cleared), the leg's wiring manifest relays that word verbatim, and a
* `"spelling-only"` judge with a covered write tool mounted also announces
* `config.write_protection_target_view_absent` exactly once per run; the disclosure changes no verdict —
* the absence law it makes readable is the judge's own and stands unaltered.
*/
writeProtection?: {
targetView: WriteProtectionTargetView;
};
/**
* EFFECTIVE half only; the present-iff law is the contract sentence below. `builtinTiers` names the
* tiers that MATERIALLY activate rows, in {@link
* import("../tools/fs/read-deny.js").READ_DENY_BUILTIN_TIERS} order — not the tiers the operator
* typed: one whose every row `readDenyBuiltinExclude` removed is not named. Deliberately NOT
* reported: `readDenyPatterns`, deployment-supplied TEXTS rather than an enum, so absence means "no
* BUILT-IN row judges", never "no read is deny-judged". IN the fingerprint (the
* {@link WiringManifest.writeProtection} class): the selection follows the deployment seat, so legs
* of one assembly agree.
*
* @contract read_deny.builtin_activation_disclosed — WHETHER the built-in sensitive-path read deny
* table judges a leg is DISCLOSED, never inferred: the tier selection is the deployment's (absent = the default
* tiers, an explicit `[]` = none), the leg that compiles the judge relays the tiers its own resolution materially
* activated, and the manifest carries that section iff at least one built-in row is active (absence
* = no built-in row judges; an empty array is never emitted — "off" and "on to nothing" are one
* fact). The disclosure changes no verdict.
*/
readDeny?: {
builtinTiers: readonly string[];
};
/**
* EFFECTIVE half only. PRESENT IFF auto-consolidation is EFFECTIVELY armed on this
* deployment (`autoRunOnRecommendationEffective`: an explicit `true`, or an absent seat under the
* named default `AUTO_RUN_ON_RECOMMENDATION_DEFAULT` where both consolidation seats are wired): a
* terminal harvest that crosses the threshold auto-runs one host consolidation — memory content
* auto-egresses to the configured model. ABSENT (and the manifest, including `configFingerprint`,
* byte-identical) when not armed — an explicit `false`, or a default that does not arm it.
* IN the fingerprint (an assembly fact, the same class as {@link WiringManifest.writeProtection}); always
* `{ onRecommendation: true }` when present — the prepare door refuses an armed-but-unrunnable state.
*/
autoConsolidation?: {
onRecommendation: true;
};
/**
* EFFECTIVE half only, ALWAYS present on an engine-minted effective manifest: does this leg capture file history.
* `"on"` — it records (store wired, neither layer declared it off, a filesystem env mounted). `"disabled"` — it does
* not, whichever layer or missing half made it so (`TaskSpec.fileHistory`, `RunnerDeps.fileHistoryStore: "disabled"`, `RunnerDeps.fileHistoryCapture: "off"`,
* no store, no filesystem env); the host knows its own deployment seat. ABSENT = an older mint or an external
* derivation, never a state. Out of {@link configFingerprint}: the request word is a per-task seat (`hooks` reasoning).
*/
fileHistory?: "on" | "disabled";
/** EFFECTIVE half only — a short, non-sensitive fingerprint (sha256 prefix over the canonical
* JSON of this manifest's own resolved facts; every field here is an enum/boolean/count, no
* secrets) so an operator can correlate legs that ran under the same resolved assembly. */
configFingerprint?: string;
}
/**
* The FULL fact set both halves derive from — one input shape, one derivation
* ({@link deriveWiringManifest}), so the halves cannot drift. `undefined` on the optional park
* atoms means "not knowable at this half" and derives `"unresolved"`, never a guess.
*/
export interface WiringFacts {
half: "static" | "effective";
/** Required on the effective half; must be absent on the static half. */
leg?: WiringLegKind;
/** Effective half only — see {@link WiringManifest.teamRole}. */
teamRole?: import("../agents/team-role.js").TeamRole;
/** Effective half only — see {@link WiringManifest.peerPresence}; copied, never aliased. */
peerPresence?: import("../agents/peer-directory.js").PeerPresence;
askForm: AskSeamForm;
askProvenance?: SeamProvenance;
questionWired: boolean;
questionProvenance?: SeamProvenance;
/** The engine-minted strip flag (trusted RunInternals channel) — effective half only; the static
* half has no run internals and never reports `stripped_bg_lane`. */
questionStrippedByEngine?: boolean;
/** F13 composition-lie fact (effective half only). */
interactiveToolsWithoutDeliveryFace?: boolean;
/** The interaction-posture declaration this half can see: the static half reads `spec ?? deps`,
* the effective half reports the RESOLVED posture (spec > spawning parent > deps). Absent = no
* declaration anywhere — reported as `"absent"`, never guessed. */
interactionPosture?: "interactive" | "headless";
elicitSeamWired: boolean;
elicitServersOptedIn: number;
parkCapable: boolean;
parkDurableApprovalOptIn: boolean;
/** `undefined` = unresolved at this half (per-principal runtime caps are a prepare-time fact). */
parkForceDurableGate?: boolean;
/** `undefined` = unresolved at this half (the irreversible/egress tool vocabulary and the shell read station —
* the three sources of a mandated ask — are assembled in prepare). */
parkSafetyVocabularyArmed?: boolean;
/** Present iff `parkCapable` (the resolved checkpoint store's declaration). */
checkpointDurability?: StoreDurability;
sessionDurability: StoreDurability;
backgroundAgentStoreWired: boolean;
/** Subagent transcript persistence — the declared delegation-transcript tier (see
* {@link WiringManifest.fleet}). Optional for external `deriveWiringManifest` callers: absent
* derives fail-closed from `backgroundAgentStoreWired` alone (`rows`/`none` — under-promise,
* never `full`); the engine's own halves always pass the resolved value. */
subagentTranscriptTier?: SubagentTranscriptTier;
/** design/179 — a persisted allow-rule store provider is wired. */
permissionRuleStoreWired: boolean;
/** design/182 §9 — the deployment declared that it drives cloud sync for that store. */
permissionRuleSyncWired: boolean;
/** design/182 §7 — the deployment declared org governance (an org rule overlay is wired). */
permissionRuleOrgGoverned: boolean;
hostChildEventSinkWired: boolean;
lockedConfigWired: boolean;
complianceWired: boolean;
memoryAdmissionWired: boolean;
retentionPolicyWired: boolean;
/** Effective half only — see {@link WiringManifest.modelGate}; the static half has no roster to trim. */
modelGate?: {
class: string;
removed: readonly string[];
restore: string;
};
/** Effective half only — see {@link WiringManifest.autoMode}; the static half has no leg to arm.
* `armed` must agree with `reason` (`armed ⇔ reason === "armed"`); a contradicting pair is refused, and so
* is a `deniedSource` beside any reason but `denied` or spelled outside its closed set. */
autoMode?: AutoModeArmFact;
/** Effective half only — see {@link WiringManifest.mcp}; the static half materializes nothing.
* Copied entry-wise onto the manifest (the caller's array is never aliased). */
mcp?: readonly WiringManifestMcpEntry[];
/** Effective half only — the leg's minted tool roster (see {@link WiringManifest.tools}). */
tools?: import("./tool-roster.js").ToolRoster;
/** Effective half only — the wired hook seats ({@link WiringManifest.hooks}); an empty array and an absent value derive the same thing (no section). */
hooks?: readonly WiringManifestHookEntry[];
/** Effective half only — the LSP seam ({@link WiringManifest.lsp}); absent ⇒ no manager wired. */
lsp?: {
mounted: boolean;
lane?: LspLane;
};
/** Effective half only — the hands seam ({@link WiringManifest.hands}, {@link deriveHandsSeam}); the engine always passes it. */
hands?: {
mounted: boolean;
reason?: HandsUnmountedReason;
};
/** Effective half only — the leg's permission-mode receipt ({@link WiringManifest.permissionMode}); the engine always passes it.
* Screened: `effective` a mode word, `requested` a mode word or absent, `foldedBy` a fold reason or absent. */
permissionMode?: import("./mode-policy.js").PermissionModeReceipt;
/** Effective half only — the compiled write-protection judge's OWN target-view word
* ({@link WiringManifest.writeProtection}); absent ⇒ this leg compiled no judge (an emptied table). */
writeProtectionTargetView?: WriteProtectionTargetView;
/** Effective half only — the built-in read-deny TIERS this leg's configuration materially activated
* ({@link WiringManifest.readDeny}); empty and absent derive the same thing (no section). */
readDenyBuiltinTiersActive?: readonly string[];
/** Effective half only — `RunnerDeps.autoRunOnRecommendation === true`
* ({@link WiringManifest.autoConsolidation}); false ⇒ no section (byte-identical manifest). */
autoConsolidationOnRecommendation?: boolean;
/** Effective half only — the file-history phase's word ({@link WiringManifest.fileHistory}); the engine always passes it. */
fileHistory?: "on" | "disabled";
}
/** Named view of the deps seats the static half reads (a `Pick` of the real {@link RunnerDeps} —
* single-source shapes, no parallel hand-copied interface). */
export type StaticWiringDeps = Pick<RunnerDeps, "onAsk" | "onQuestion" | "interactionPosture" | "onElicit" | "checkpointStore" | "sessionStore" | "backgroundAgentStore" | "onBackgroundChildEvent" | "lockedConfig" | "compliancePostureResolver" | "memoryScopeAdmission" | "retentionPolicy" | "permissionRuleStore" | "permissionRuleSyncWired">;
/** Named view of the spec seats the static half reads (a `Pick` of the real {@link TaskSpec}). */
export type StaticWiringSpec = Pick<TaskSpec, "onAsk" | "onQuestion" | "checkpointStore" | "durableApproval" | "mcp" | "interactiveTools" | "interactionPosture">;
/**
* Read a store's {@link StoreDurability} declaration: absent ⇒ `"process-local"` (fail-closed —
* under-promise, never over-promise), a declared value passes through, and an UNPARSEABLE value is
* refused loudly (`config.store_durability_invalid`) — a junk declaration silently folded to either
* arm would be a manifest that lies in whichever direction the fold picked.
*/
export declare function resolveDeclaredDurability(store: {
readonly durability?: StoreDurability;
} | undefined, storeName: string): StoreDurability;
/** Subagent transcript persistence — the deployment-level delegation-transcript durability tier
* (see {@link WiringManifest.fleet}). */
export type SubagentTranscriptTier = "none" | "rows" | "full";
/**
* Subagent transcript persistence — the ONE deployment-level tier derivation (pure declaration
* read, no probing, no class-name sniffing — the wiring-manifest posture): `none` without an
* agent-row store; with one, `full` iff the session store DECLARES its subagent placement
* partition durable, else `rows`. A junk placement declaration is refused loudly
* (`config.store_durability_invalid` — the resolveDeclaredDurability rule: an unparseable
* declaration silently folded to either arm would make the manifest lie in whichever direction the
* fold picked). This is the DEPLOYMENT-level judgment only; the per-handle "did this row's
* transcript actually land" question belongs to `durableAgentRowProbe` (the S1b release-flip gate)
* — two different questions, deliberately two named faces (do not merge them back into one).
*
* WHICH session store to pass: the one on the runner the Agent tool was mounted with
* (`SubagentToolOptions.runner.sessions`), because that is the store an ordinary (sync/background)
* child transcript is minted through — the fork lane deliberately branches through the HOST store
* instead, see the law on `SubagentToolOptions.runner`. A deployment that serves root tasks from one
* runner and delegated children from another (a throwaway sub-task store, a routing store) has two
* different stores here, and passing the ROOT deps' store reports the root lane's fate under the
* child lane's name. Note what the three words do and do not promise about DISK: this tier names
* ADDRESSABILITY, not persistence. `none` is returned before any store is inspected, so it covers
* both "the transcript is on disk but nothing can address it" and "there is no transcript" — an
* operator asking whether a child conversation is readable afterwards must read the delegation
* store's own durability + release/evict semantics, not this word.
*/
export declare function resolveSubagentTranscriptTier(agentStoreWired: boolean, sessionStore: {
readonly placements?: {
subagent?: {
durability: StoreDurability;
};
};
} | undefined): SubagentTranscriptTier;
/**
* The ONE `ask.effective` derivation (design/173) — shared by the effective manifest AND
* the posture door (`config.interaction_posture`): the door passes no `mode` and judges the SEAT alone, the
* manifest passes its leg's effective mode AT THE LEG'S START (the manifest is minted once; a runtime reader pairs
* {@link askSeatEffective} with the live mode instead), so the two read one table and differ only by the one fact the
* door does not have:
* - MODE BEFORE SEAT: under `dontAsk` the mode refuses every ask a policy raises (`arbitrateByMode`; only a
* hook's own ask beside no rule or safety ask is handed on, and that is the hook lane's decision, not a policy
* `ask`), so no seat answers one — whatever the seat and the park lane say, the word is `auto_deny`;
* - a live approver callback ⇒ `human_reachable` (regardless of the park lane);
* - blanket `"allow"`/`"deny"` ⇒ the park lane decides first: a string seat is NOT a live approver,
* so on an armed park lane the ask parks and the honest report is `park_only` — reporting the
* blanket as what the ask "reaches" would be a false fact of exactly the kind this module refuses.
* Off the park lane the blanket is what happens: the deliberate auto policies;
* - no seat at all ⇒ the park lane decides: armed ⇒ `park_only`, unresolved ⇒ `unresolved`,
* else the headless degrade `auto_deny`.
*/
export declare function deriveAskEffective(form: AskSeamForm, parkEffective: boolean | "unresolved", mode?: PermissionMode): AskEffective;
/**
* The SEAT's own `ask.effective` of an effective manifest — {@link deriveAskEffective} with no mode, from the manifest's own
* form and park facts. The manifest's `ask.effective` is the word AS OF THE LEG'S START under its start mode, and a steer moves
* the mode afterwards; a runtime consumer that reads the word per call (the classifier's approval seat, the posture row, the peer
* lane's mode fold) therefore reads THIS word and the leg's LIVE mode beside it — never the start-of-leg fold, which would carry a
* `dontAsk` start's refusal into the leg's later modes.
*/
export declare function askSeatEffective(manifest: Pick<WiringManifest, "ask" | "parkLane">): AskEffective;
/**
* Does an ask this leg hands on carrying `requiresRealApproval` reach a PERSON — never an automatic yes? The leg's
* APPROVAL SEAT, read off the ONE ask derivation above, never re-derived: `human_reachable` (a live approver) and
* `park_only` (the durable park; where the park cannot take the ask, a blanket seat behind it refuses the bit) are a
* person; `auto_allow`, `auto_deny` and `unresolved` are nobody (the last the fail-closed reading). The auto-mode
* classifier stations read it to decide where a classification that could not rule goes: to that person (the ask
* carrying the bit), or refused.
*/
export declare function askReachesPerson(ask: {
readonly effective?: AskEffective;
}): boolean;
export declare function deriveWiringManifest(facts: WiringFacts): WiringManifest;
/** The one ask-seat resolution (`spec` wins over `deps`), shared with the effective half so the
* form/provenance read cannot fork. Junk values (a JS caller passing something outside the OnAsk
* union) are refused loudly — a manifest must not classify what it cannot name. */
export declare function resolveAskSeamForm(spec: Pick<TaskSpec, "onAsk">, deps: Pick<RunnerDeps, "onAsk">): {
form: AskSeamForm;
provenance?: SeamProvenance;
};
/** The one question-seat resolution (`spec` wins over `deps`), shared by both halves. Review fold
* r2-F2: a NON-FUNCTION present value (a JS caller passing `onQuestion: null`/junk) is refused
* loudly — the engine's `??` resolution would keep it, the mount's presence check would count it,
* and the manifest would report `wired` for a callback nothing can ever call.
*
* design/174: "a value is present" is NOT the criterion — `wired` is derived through THE shared
* {@link isLiveQuestionFace} predicate, the same one the gate routes on. The reserved
* `QUESTION_AWAITS_RESUME` placeholder is a function and is the documented standard assembly of the
* durable topology, but its whole contract is that it never runs; reporting it as a wired channel
* told an operator a question could reach a person in-stream when the only real delivery face on
* that assembly is the park lane (which this manifest reports separately, and honestly). */
export declare function resolveQuestionSeam(spec: Pick<TaskSpec, "onQuestion">, deps: Pick<RunnerDeps, "onQuestion">): {
wired: boolean;
provenance?: SeamProvenance;
};
/** Count of MCP servers that opted into elicitation on this spec (the per-server half of the
* elicit capability — statically readable). */
export declare function countElicitOptIns(spec: Pick<TaskSpec, "mcp">): number;
/** The one elicit-seat resolution, shared by both halves (review fold r3-F3 — the onQuestion rule
* applies here too): absent ⇒ not wired; a function ⇒ wired; a present NON-function (a JS caller
* passing null/junk) is refused loudly rather than reported as a live seam nothing can call. */
export declare function resolveElicitSeam(deps: Pick<RunnerDeps, "onElicit">): boolean;
/**
* design/173 §2.1 — the STATIC half: a pure synchronous description of what `(deps, spec)` can
* prove about the wiring, for a server's startup self-check. Facts that only prepare can resolve
* (per-principal runtime caps, the safety-tool vocabulary) derive `"unresolved"`; `ask.effective`
* is omitted entirely (see the module doc). This is DISCLOSURE, not verification — see the §0
* guarantee boundary above. `spec` may be omitted for a spec-less deployment self-check.
*/
export declare function describeStaticWiring(deps: StaticWiringDeps, spec?: StaticWiringSpec): WiringManifest;