zigmini 1.0.0-beta.2 → 1.1.0-beta.1

package/src/agent/tool-delivery.ts

@@ -0,0 +1,359 @@
+/**
+ * 294 item 5: the gateway side of a granted agent tool operation (plan C4/C5/C6/C10). src/main.ts runs it in the gateway
+ * process, so it lives under src/ (the Docker image and the packaged gateway ship src/ without host/).
+ *
+ * - enginePolicy: the exact policy the engine applies (zgw.agent_tool_policy). Blocked access or no grant never allows.
+ * - deliverGrantedOperation: policy ACK -> reserve -> start CAS -> one engine execute -> stored result -> one resume.
+ *   A start without a result, a lost execute response and outcome_unknown are never executed again (C5).
+ *   A collaboration request only stores the owner outcome; the 292 dispatcher owns that continuation (292 N6).
+ * - authorizeRecipientTool: the recipient check 292 calls at start/dispatch/helper start and final release.
+ *   Sender grants never transfer: only the recipient's own active grant of the current epoch counts.
+ * - createAgentToolDeliverer: the production trigger over the Store ledger.
+ */
+import { createHash } from "node:crypto";
+import type { AgentAccessView } from "./tool-permission-types.ts";
+import type { SessionAsideTarget } from "./aside-target-routes.ts";
+
+export interface GrantView {
+	readonly id: string;
+	readonly agentId: string;
+	readonly incarnation: number;
+	readonly authorityEpoch: number;
+	readonly toolKey: { readonly sourceKind: string; readonly ownerId: string; readonly originalName: string; readonly registrationDigest: string };
+	readonly operations: readonly string[];
+	readonly state: "active" | "revoked" | "suspended";
+	readonly revision: number;
+	/** Approved resources from the ledger; null for a legacy grant without stored resources. */
+	readonly resources?: readonly string[] | null;
+}
+
+export interface EnginePolicy {
+	readonly revision: number;
+	/** `resources` is informational for the engine (it matches by name); the adapters enforce it at the tool boundary. */
+	readonly grants: readonly { readonly toolName: string; readonly owner?: string; readonly operation?: string; readonly resources: readonly string[] }[];
+	readonly missing: "hold" | "deny";
+}
+
+const usable = (view: AgentAccessView, grant: GrantView, agentId: string) =>
+	grant.agentId === agentId && grant.state === "active" && grant.authorityEpoch === view.authorityEpoch && grant.incarnation === view.lifecycleEpoch;
+
+/** The engine's operation id of a held direct call (agent-session.js `agent-op:${toolCall.id}`). The ledger stores it as the logical call. */
+export const agentToolOperationId = (toolCallId: string) => `agent-op:${toolCallId}`;
+/** The engine operation the session records for a click/fill awaiting its one-shot confirmation (C8); the ledger stores it as the logical call. */
+export const agentToolActionId = (toolCallId: string) => `agent-action:${toolCallId}`;
+
+/**
+ * Tools an agent session runs without a persistent grant: ask_user_question (bootstrap communication, C1) and
+ * zgw_attachment_read (its own 293 selection grant is checked per call by the gateway route, C10), and the collaboration
+ * tools host/omo-bridge/agent-collaboration.ts registers (COLLABORATION_TOOLS; F3 D2: the gateway's collaboration routes
+ * check targets, artifacts and the recipient's grants per call, so a card would only stall the request). Added to every
+ * policy the engine applies, so a pushed policy never holds them; a blocked agent (missing: "deny") gets none.
+ */
+export const SESSION_BASELINE_TOOLS: readonly string[] = ["ask_user_question", "zgw_attachment_read", "zgw_agent_request", "zgw_agent_result", "zgw_agent_requests", "zgw_agent_cancel", "zgw_agent_files"];
+export function withSessionBaseline(policy: EnginePolicy): EnginePolicy {
+	if (policy.missing === "deny") return policy;
+	return { ...policy, grants: [...policy.grants, ...SESSION_BASELINE_TOOLS.map((toolName) => ({ toolName, resources: [] }))] };
+}
+
+/** The catalog operations each usable grant allows, by tool name; adapters check one operation against it (C7). */
+export function grantedOperations(view: AgentAccessView, grants: readonly GrantView[]): Record<string, string[]> {
+	const out: Record<string, string[]> = {};
+	if (view.accessState === "blocked") return out;
+	for (const grant of grants) {
+		if (!usable(view, grant, view.agentId)) continue;
+		const name = grant.toolKey.originalName;
+		out[name] = [...new Set([...(out[name] ?? []), ...grant.operations])].sort();
+	}
+	return out;
+}
+
+/** The policy for one agent. Blocked access pushes no grant and refuses instead of holding (C10). */
+export function enginePolicy(view: AgentAccessView, grants: readonly GrantView[]): EnginePolicy {
+	if (view.accessState === "blocked") return { revision: Math.max(view.policyRevision, 1), grants: [], missing: "deny" };
+	const out: { toolName: string; owner?: string; operation?: string; resources: readonly string[] }[] = [];
+	for (const grant of grants) {
+		if (!usable(view, grant, view.agentId)) continue;
+		const resources = grant.resources ?? [];
+		if (grant.toolKey.sourceKind === "mcp") for (const operation of grant.operations) out.push({ toolName: grant.toolKey.originalName, owner: grant.toolKey.ownerId, operation, resources });
+		else out.push({ toolName: grant.toolKey.originalName, resources });
+	}
+	return { revision: Math.max(view.policyRevision, 1), grants: out, missing: "hold" };
+}
+
+export interface RecipientToolCall {
+	readonly recipientAgentId: string;
+	readonly toolKey: GrantView["toolKey"];
+	readonly operation: string;
+	/** The recipient authority epoch bound when 292 admitted the request. */
+	readonly authorityEpoch: number;
+}
+export type RecipientToolOutcome =
+	| { readonly decision: "allow"; readonly grantId: string; readonly grantRevision: number; readonly authorityEpoch: number }
+	| { readonly decision: "deny"; readonly reason: "agent_access_blocked" | "authority_epoch_mismatch" | "agent_mismatch" | "no_recipient_grant" };
+
+/**
+ * 292 recipient check. Order (C10): access state -> authority epoch -> the recipient's own exact grant. Read the view and
+ * grants in the same Store transaction as the start or release; the result is a snapshot, not a lease.
+ */
+export function authorizeRecipientTool(view: AgentAccessView, grants: readonly GrantView[], call: RecipientToolCall): RecipientToolOutcome {
+	if (view.agentId !== call.recipientAgentId) return { decision: "deny", reason: "agent_mismatch" };
+	if (view.accessState === "blocked") return { decision: "deny", reason: "agent_access_blocked" };
+	if (view.authorityEpoch !== call.authorityEpoch) return { decision: "deny", reason: "authority_epoch_mismatch" };
+	const grant = grants.find((g) => usable(view, g, call.recipientAgentId) &&
+		g.toolKey.originalName === call.toolKey.originalName && g.toolKey.registrationDigest === call.toolKey.registrationDigest &&
+		g.toolKey.ownerId === call.toolKey.ownerId && g.toolKey.sourceKind === call.toolKey.sourceKind && g.operations.includes(call.operation));
+	return grant ? { decision: "allow", grantId: grant.id, grantRevision: grant.revision, authorityEpoch: grant.authorityEpoch }
+		: { decision: "deny", reason: "no_recipient_grant" };
+}
+
+export interface LedgerInvocation {
+	readonly state: "ready" | "reserved" | "started" | "succeeded" | "failed" | "outcome_unknown" | "cancelled";
+	readonly agentId: string;
+	readonly executorGeneration: number;
+	readonly resultRef: string | null;
+}
+/** The gateway ledger, in process (Store) or over the signed internal routes. */
+export interface AgentToolLedgerPort {
+	invocation(id: string): LedgerInvocation | null | Promise<LedgerInvocation | null>;
+	policy(agentId: string): { view: AgentAccessView; grants: readonly GrantView[] } | Promise<{ view: AgentAccessView; grants: readonly GrantView[] }>;
+	policyAck(revision: number): void | Promise<void>;
+	reserve(id: string, generation: number): unknown;
+	start(id: string, generation: number): { state: "started" } | { state: "cancelled"; reason: string } | Promise<{ state: "started" } | { state: "cancelled"; reason: string }>;
+	result(id: string, generation: number, outcome: { state: "succeeded" | "failed" | "outcome_unknown"; resultRef: string }): { continuationId: string } | Promise<{ continuationId: string }>;
+}
+/** The engine's host-only RPC commands (item 3 patch). */
+export interface AgentToolEnginePort {
+	policy(policy: EnginePolicy): Promise<{ revision: number }>;
+	execute(operationId: string): Promise<{ executed: boolean; state: string; result?: unknown }>;
+	resume(operationId: string, continuationId: string): Promise<{ accepted: boolean; duplicate: boolean }>;
+	/** agent-control exposes the granted schemas only after the ACK (zgw.agent_tool_tools). */
+	expose?(revision: number, names: readonly string[]): Promise<unknown>;
+}
+
+export type DeliveryOutcome =
+	| { readonly state: "resumed" | "duplicate"; readonly continuationId: string }
+	| { readonly state: "stored"; readonly continuationId: string }
+	| { readonly state: "cancelled"; readonly reason: string }
+	| { readonly state: "policy_unacknowledged"; readonly revision: number }
+	| { readonly state: "outcome_unknown"; readonly reason: "started_without_result" | "execute_response_lost" | "engine_unknown" }
+	| { readonly state: "not_deliverable"; readonly reason: string };
+
+export const resultRef = (result: unknown) => `sha256:${createHash("sha256").update(JSON.stringify(result ?? null)).digest("hex")}`;
+
+/**
+ * Runs one granted operation at most once and continues the original work at most once. Calling it again after a
+ * success only re-delivers the stored continuation (the engine deduplicates by continuation id); nothing re-runs.
+ */
+export async function deliverGrantedOperation(
+	ports: { ledger: AgentToolLedgerPort; engine: AgentToolEnginePort; beforeExecute?: () => Promise<unknown> },
+	input: { invocationId: string; operationId: string; generation: number; collaboration: boolean },
+): Promise<DeliveryOutcome> {
+	const { ledger, engine } = ports;
+	const current = await ledger.invocation(input.invocationId);
+	if (!current) return { state: "not_deliverable", reason: "invocation_not_found" };
+	if (current.state === "succeeded" || current.state === "failed") {
+		const { continuationId } = await ledger.result(input.invocationId, current.executorGeneration, { state: current.state, resultRef: current.resultRef ?? "" });
+		return continueOnce(engine, input, continuationId);
+	}
+	if (current.state === "started") return { state: "outcome_unknown", reason: "started_without_result" };
+	if (current.state !== "ready" && current.state !== "reserved") return { state: "not_deliverable", reason: current.state };
+	// Grant first, then the engine's ACK of that exact revision, then the start CAS (C4 steps 3-5, C5).
+	const { view, grants } = await ledger.policy(current.agentId);
+	const policy = enginePolicy(view, grants);
+	const ack = await engine.policy(policy);
+	if (ack.revision !== policy.revision) return { state: "policy_unacknowledged", revision: policy.revision };
+	try {
+		await ledger.policyAck(policy.revision);
+	} catch (error) {
+		// A revoke between the engine ACK and its record raised the revision and cancelled the row: the cancelled row wins (C5).
+		if ((await ledger.invocation(input.invocationId))?.state === "cancelled") return { state: "cancelled", reason: "cancelled" };
+		throw error;
+	}
+	await engine.expose?.(policy.revision, grantedToolNames(policy));
+	await ledger.reserve(input.invocationId, input.generation);
+	const started = await ledger.start(input.invocationId, input.generation);
+	if (started.state === "cancelled") return { state: "cancelled", reason: started.reason };
+	// C8: an action's one-shot confirmation reaches the session only after start consumed its ticket.
+	await ports.beforeExecute?.();
+	let executed: Awaited<ReturnType<AgentToolEnginePort["execute"]>>;
+	try {
+		executed = await engine.execute(input.operationId);
+	} catch {
+		// The request may have run. A lost answer is never a reason to run again; the row stays started for review.
+		return { state: "outcome_unknown", reason: "execute_response_lost" };
+	}
+	const state = executed.state === "succeeded" ? "succeeded" : executed.state === "failed" || executed.state === "not_granted" ? "failed" : "outcome_unknown";
+	const { continuationId } = await ledger.result(input.invocationId, input.generation, { state, resultRef: resultRef(executed.result ?? executed.state) });
+	if (state === "outcome_unknown") return { state: "outcome_unknown", reason: "engine_unknown" };
+	return continueOnce(engine, input, continuationId);
+}
+
+async function continueOnce(engine: AgentToolEnginePort, input: { operationId: string; collaboration: boolean }, continuationId: string): Promise<DeliveryOutcome> {
+	// 292 N6: the collaboration continuation belongs to the 292 dispatcher alone; 294 does not prompt.
+	if (input.collaboration) return { state: "stored", continuationId };
+	const resumed = await engine.resume(input.operationId, continuationId);
+	return { state: resumed.accepted ? "resumed" : "duplicate", continuationId };
+}
+
+/**
+ * The engine answers an accepted continuation through its prompt admission (`{disposition, clientInputId, admission?}`,
+ * connection-handler.js zgw.agent_tool_resume -> handleClientInput), not with `accepted`; only a repeat of the same
+ * continuation answers `{accepted:false, duplicate:true}`. Anything else is not an answer the delivery can classify.
+ */
+export function resumeAnswer(answer: unknown): { accepted: boolean; duplicate: boolean } {
+	const value = answer as { accepted?: unknown; duplicate?: unknown; disposition?: unknown } | null | undefined;
+	if (value?.duplicate === true) return { accepted: false, duplicate: true };
+	if (value?.accepted === false) return { accepted: false, duplicate: false };
+	if (value?.accepted === true || typeof value?.disposition === "string") return { accepted: true, duplicate: false };
+	throw new Error("agent_tool_resume_answer_invalid");
+}
+
+/** Engine port over an RPC command function (OmoClient.command with the session id, or a direct handler). */
+export function engineCommands(command: (type: string, params: Record<string, unknown>) => Promise<unknown>): AgentToolEnginePort {
+	return {
+		policy: async (policy) => command("zgw.agent_tool_policy", { policy: withSessionBaseline(policy) }) as Promise<{ revision: number }>,
+		execute: async (operationId) => command("zgw.agent_tool_execute", { operationId }) as Promise<{ executed: boolean; state: string; result?: unknown }>,
+		resume: async (operationId, continuationId) => resumeAnswer(await command("zgw.agent_tool_resume", { operationId, continuationId })),
+		expose: async (revision, names) => command("extension_request", { name: "zgw.agent_tool_tools", data: { revision, names } }),
+	};
+}
+
+export type SessionPolicyOutcome =
+	| { readonly state: "applied"; readonly revision: number }
+	| { readonly state: "legacy" }
+	| { readonly state: "policy_unacknowledged"; readonly revision: number };
+
+/**
+ * D2: a managed agent session gets the authority when it opens, before any turn: the current policy is applied, its
+ * ACK persisted for that durable session, and the granted schemas exposed. A held call then waits for consent instead
+ * of being refused, and a later allow starts without a new ACK race. A legacy agent keeps the previous rules (C9).
+ */
+export async function pushSessionPolicy(
+	ports: { ledger: Pick<DeliveryLedger, "policyGrants" | "ackPolicy"> & { mode(agentId: string): "legacy" | "managed" }; engine: AgentToolEnginePort },
+	input: { agentId: string; durableSessionId: string },
+): Promise<SessionPolicyOutcome> {
+	if (ports.ledger.mode(input.agentId) !== "managed") return { state: "legacy" };
+	const { view, grants } = ports.ledger.policyGrants(input.agentId);
+	const policy = enginePolicy(view, grants);
+	const ack = await ports.engine.policy(policy);
+	if (ack.revision !== policy.revision) return { state: "policy_unacknowledged", revision: policy.revision };
+	ports.ledger.ackPolicy(input.durableSessionId, input.agentId, policy.revision);
+	await ports.engine.expose?.(policy.revision, grantedToolNames(policy));
+	return { state: "applied", revision: policy.revision };
+}
+
+/** The ledger calls the production deliverer uses (src/agent/tool-permissions.ts AgentToolPermissionStore). */
+export interface DeliveryLedger {
+	deliveryTarget(invocationId: string): { invocationId: string; operationId: string; agentId: string; convId: string; durableSessionId: string; collaboration: boolean } | null;
+	readyInvocations(convId: string): string[];
+	invocation(id: string): LedgerInvocation | null;
+	policyGrants(agentId: string): { view: AgentAccessView; grants: readonly GrantView[] };
+	ackPolicy(durableSessionId: string, agentId: string, revision: number): unknown;
+	reserve(id: string, generation: number): unknown;
+	start(id: string, generation: number, ack: { durableSessionId: string }): { state: "started" } | { state: "cancelled"; reason: string };
+	result(id: string, generation: number, outcome: { state: "succeeded" | "failed" | "outcome_unknown"; resultRef: string }): { continuationId: string };
+	/** C4 queued -> continued, persisted once the engine accepted the continuation or already had it. */
+	continued(continuationId: string): unknown;
+	/** Started executions a generation that is not live in this process left without a result (C5: outcome unknown). */
+	staleStarted(convId: string): string[];
+}
+export type ProductionDelivery = DeliveryOutcome | { readonly state: "collaboration_owned" } | { readonly state: "engine_unavailable" } | { readonly state: "in_flight" };
+
+/**
+ * The production trigger after an owner allow and after a session opens. One delivery per execution at a time; the ACK is
+ * persisted for the target session and start requires it. A collaboration request is never run here (292 N6), and a
+ * conversation without a live session keeps its execution ready until that session opens.
+ */
+export function createAgentToolDeliverer(deps: {
+	ledger: DeliveryLedger;
+	engine: (convId: string) => ((type: string, params: Record<string, unknown>) => Promise<unknown>) | null;
+	generation: number;
+	/** D4: the tab the owner bound to the call (sessionAsideTarget over the gateway registry); null for other calls. */
+	target?: (invocationId: string) => { args: unknown; target: SessionAsideTarget } | { unavailable: string } | null;
+	/** C8: the stored args and ticket of an action execution (ledger actionCarry); null for other executions. */
+	action?: (invocationId: string) => { args: unknown; ticket: string } | null;
+	/** C5: an outcome that cannot be proven goes to the owner's needs_review surface (Store.reviewAgentToolOutcome). */
+	review?: (invocationId: string, reason: string) => void;
+}) {
+	const flying = new Set<string>();
+	const bindings = new Map<string, Promise<unknown>>();
+	const deliver = async (invocationId: string): Promise<ProductionDelivery> => {
+		const target = deps.ledger.deliveryTarget(invocationId);
+		if (!target) return { state: "not_deliverable", reason: "invocation_not_found" };
+		if (target.collaboration) return { state: "collaboration_owned" };
+		const command = deps.engine(target.convId);
+		if (!command) return { state: "engine_unavailable" };
+		if (flying.has(invocationId)) return { state: "in_flight" };
+		flying.add(invocationId);
+		try {
+			const outcome = await deliverOnce(invocationId, target, command);
+			// C4: the accepted (or already held) continuation is persisted, so a restart never delivers it again.
+			if (outcome.state === "resumed" || outcome.state === "duplicate") deps.ledger.continued(outcome.continuationId);
+			if (outcome.state === "outcome_unknown") deps.review?.(invocationId, outcome.reason);
+			return outcome;
+		} finally {
+			flying.delete(invocationId);
+		}
+	};
+	const deliverOnce = async (invocationId: string, target: NonNullable<ReturnType<DeliveryLedger["deliveryTarget"]>>,
+		command: (type: string, params: Record<string, unknown>) => Promise<unknown>): Promise<ProductionDelivery> => {
+		const { ledger } = deps;
+		const action = deps.action?.(invocationId) ?? null;
+		const carry = (data: unknown) => command("extension_request", { name: "zgw.aside_action", data });
+		const run = async () => {
+			try {
+				return await deliverGrantedOperation({
+					engine: engineCommands(command),
+					ledger: {
+						invocation: (id) => ledger.invocation(id),
+						policy: (agentId) => ledger.policyGrants(agentId),
+						policyAck: (revision) => { ledger.ackPolicy(target.durableSessionId, target.agentId, revision); },
+						reserve: (id, generation) => ledger.reserve(id, generation),
+						start: (id, generation) => ledger.start(id, generation, { durableSessionId: target.durableSessionId }),
+						result: (id, generation, outcome) => ledger.result(id, generation, outcome),
+					},
+					...(action ? { beforeExecute: () => carry(action) } : {}),
+				}, { invocationId, operationId: target.operationId, generation: deps.generation, collaboration: false });
+			} finally {
+				if (action) await carry({ args: action.args, ticket: null })
+					.catch((error: unknown) => console.error(`aside action clear failed (${target.convId}): ${error instanceof Error ? error.message : String(error)}`));
+			}
+		};
+		const bound = deps.target?.(invocationId) ?? null;
+		if (bound === null) return await run();
+		// A bound tab that can no longer be used never starts the call; the execution stays ready for a new selection.
+		if ("unavailable" in bound) return { state: "not_deliverable", reason: `target_${bound.unavailable}` };
+		// The engine runs the stored args unchanged; the session matches the carried tab to the call by those args, so
+		// target-bound deliveries of one conversation run one at a time.
+		const turn = (bindings.get(target.convId) ?? Promise.resolve()).then(async () => {
+			await command("extension_request", { name: "zgw.aside_target", data: bound });
+			try {
+				return await run();
+			} finally {
+				await command("extension_request", { name: "zgw.aside_target", data: { args: bound.args, target: null } })
+					.catch((error: unknown) => console.error(`aside target clear failed (${target.convId}): ${error instanceof Error ? error.message : String(error)}`));
+			}
+		});
+		bindings.set(target.convId, turn.then(() => undefined, () => undefined));
+		return await turn;
+	};
+	/**
+	 * When the conversation's session opens: every execution still owed a delivery (ready, a dead reservation, a stored
+	 * result whose continuation is queued) is delivered once; a dead generation's start without a result goes to review.
+	 */
+	const deliverReady = async (convId: string): Promise<ProductionDelivery[]> => {
+		const out: ProductionDelivery[] = [];
+		for (const id of deps.ledger.staleStarted(convId)) {
+			deps.review?.(id, "started_without_result");
+			out.push({ state: "outcome_unknown", reason: "started_without_result" });
+		}
+		for (const id of deps.ledger.readyInvocations(convId)) out.push(await deliver(id));
+		return out;
+	};
+	return { deliver, deliverReady };
+}
+
+/** Tools the agent session exposes after the engine ACKed a grant (C5: schema after save and ACK). */
+export function grantedToolNames(policy: EnginePolicy): string[] {
+	return policy.missing === "deny" && policy.grants.length === 0 ? [] : [...new Set(policy.grants.map((grant) => grant.toolName))];
+}

package/src/agent/tool-permission-types.ts

@@ -0,0 +1,81 @@
+/** Shared types for 294 agent tool permissions. The ledger (C2) and APIs (C3) build on these shapes. */
+
+/** Collaboration contract (292 contract, AgentAccessView). 294 owns the values; 292 only reads them. */
+export interface AgentAccessView {
+	readonly agentId: string;
+	readonly lifecycleEpoch: number;
+	readonly accessState: "open" | "blocked";
+	readonly authorityEpoch: number;
+	readonly policyRevision: number;
+}
+
+export type ToolEffect = "read" | "local_write" | "external_write" | "execution" | "control";
+export type ToolSourceKind = "builtin" | "extension" | "mcp" | "gateway";
+export type ToolAvailability = "registered" | "mcp_dynamic" | "gateway_agent" | "gateway_work" | "internal_provider" | "planned" | "unknown";
+export type ToolKind =
+	| "file_read" | "file_write" | "exec" | "exec_control" | "web" | "media" | "display" | "lsp" | "mcp_docs" | "mcp_ast"
+	| "mcp_resource" | "mcp_proxy" | "browser" | "subtask" | "session" | "self_state" | "memory" | "relocation"
+	| "communication" | "discovery" | "work_role" | "agent_history" | "attachment" | "bootstrap" | "unclassified";
+export type RestrictionAdapter =
+	| "path_scope" | "restricted_exec" | "owned_exec_handle" | "web_origin" | "media_io" | "display_surface" | "browser_target"
+	| "owned_child" | "owned_session" | "self_state" | "self_identity" | "relocation_target" | "metadata_only" | "role_only"
+	| "own_history" | "attachment_selection" | "mcp_resource" | "mcp_proxy" | "not_grantable" | "exact_args";
+
+/** Permission identity. The exposed (display) name is not part of it. */
+export interface ToolKey {
+	readonly sourceKind: ToolSourceKind;
+	readonly ownerId: string;
+	readonly originalName: string;
+	readonly registrationDigest: string;
+}
+
+/** Registration metadata as read from the engine tool list or an MCP registration. Never executes the tool. */
+export interface RegisteredToolMeta {
+	readonly name: string;
+	readonly sourceKind: ToolSourceKind;
+	readonly ownerId: string;
+	readonly originalName: string;
+	readonly parameters: unknown;
+}
+
+export interface ToolDescriptor {
+	readonly key: ToolKey;
+	readonly exposedName: string;
+	readonly kind: ToolKind;
+	readonly effect: ToolEffect;
+	readonly operations: readonly string[];
+	readonly scopeSchema: string;
+	readonly availability: ToolAvailability;
+	readonly restrictionAdapter: RestrictionAdapter;
+	readonly registrationDigest: string;
+	readonly opaque: boolean;
+	readonly bootstrap: boolean;
+	readonly grantable: boolean;
+	readonly roleOnly: "work" | null;
+}
+
+export type GrantState = "active" | "revoked" | "suspended";
+
+export interface ToolGrant {
+	readonly id: string;
+	readonly agentId: string;
+	/** 292 agent_lifecycle.epoch at grant time. */
+	readonly incarnation: number;
+	readonly authorityEpoch: number;
+	readonly toolKey: ToolKey;
+	readonly operations: readonly string[];
+	readonly state: GrantState;
+	readonly revision: number;
+}
+
+export type DenyReason =
+	| "agent_access_blocked" | "lifecycle_epoch_mismatch" | "authority_epoch_mismatch" | "not_grantable" | "role_only"
+	| "unknown_operation" | "no_grant" | "grant_agent_mismatch" | "grant_not_active" | "grant_tool_mismatch"
+	| "operation_not_granted" | "proxy_target_unresolved";
+
+export type AuthorizationOutcome =
+	| { readonly decision: "allow" }
+	| { readonly decision: "deny"; readonly reason: DenyReason }
+	| { readonly decision: "hold"; readonly reason: "tool_changed" };
+
+export type GrantReconcile = { readonly state: "active" } | { readonly state: "suspended"; readonly reason: "tool_changed" } | { readonly state: "unrelated" };