attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/execution/exec.js

@@ -0,0 +1,282 @@
+import { digestOf } from "../semantic/canonical.js";
+import { BudgetExceeded, Dispatcher } from "../attention/budget.js";
+import { HandleStore } from "./handles.js";
+import { PolicyEngine } from "../policy/policy.js";
+import { digestTool, pinTools, verifyToolPins } from "./pin.js";
+import { textOf } from "../module/mcp/protocol.js";
+import { BoundaryRejection, parseToolCall } from "../boundary/index.js";
+export class DriftDetected extends Error {
+    code = "security_event";
+    receipt;
+    constructor(message, receipt) {
+        super(message);
+        this.name = "DriftDetected";
+        this.receipt = receipt;
+    }
+}
+export class ApprovalRequired extends Error {
+    code = "approval_required";
+    receipt;
+    reason;
+    constructor(tool, receipt, reason = "action requires explicit host approval") {
+        super(`tool ${tool} is not read-only and requires explicit approval: ${reason}`);
+        this.name = "ApprovalRequired";
+        this.receipt = receipt;
+        this.reason = reason;
+    }
+}
+export class PolicyDenied extends Error {
+    code = "denied";
+    receipt;
+    constructor(message, receipt) {
+        super(message);
+        this.name = "PolicyDenied";
+        this.receipt = receipt;
+    }
+}
+/**
+ * Map MCP annotations onto the policy taxonomy.
+ */
+const effectFor = (tool) => {
+    if (tool.annotations?.readOnlyHint === true) {
+        return "read";
+    }
+    if (tool.annotations?.destructiveHint === true) {
+        return "deploy";
+    }
+    return "write-irreversible";
+};
+/**
+ * Exec profile: MCP tools behind the same budget, shaping, and receipt rules
+ * as any other action. Digest pinning makes a post-approval metadata change a
+ * security event rather than a surprise (Deadbugz / MCPoison).
+ */
+export class ExecProfile {
+    client;
+    dispatcher;
+    /**
+     * Host policy engine; `approveTool`/`policy.approve` are host-only APIs.
+     */
+    policy;
+    handles;
+    now;
+    maxResultTokens;
+    onReceipt;
+    guard;
+    verifyPinsAtCall;
+    validateArgs;
+    catalog;
+    seq = 0;
+    constructor(client, options) {
+        this.client = client;
+        this.handles = options.handles;
+        this.now = options.now;
+        this.maxResultTokens = options.maxResultTokens ?? 1200;
+        this.onReceipt = options.onReceipt;
+        this.guard = options.guard;
+        this.verifyPinsAtCall = options.verifyPinsAtCall ?? true;
+        this.validateArgs = options.validateArgs ?? true;
+        this.policy =
+            options.policy ??
+                new PolicyEngine({
+                    now: options.now,
+                    approvalEffects: options.requireApproval === false ? new Set() : undefined,
+                });
+        this.dispatcher = new Dispatcher(options.budget);
+    }
+    async connect() {
+        await this.client.negotiate();
+        const list = await this.client.listTools();
+        const pins = pinTools(list.tools);
+        const snapshot = {
+            tools: list.tools,
+            digest: pins.catalog,
+            pins,
+            ttlMs: list.ttlMs,
+            expiresAt: Date.now() + list.ttlMs,
+        };
+        this.catalog = snapshot;
+        return snapshot;
+    }
+    /**
+     * Re-list and compare. Any changed, added or removed tool fails closed.
+     */
+    async refresh() {
+        const list = await this.client.listTools();
+        const pins = pinTools(list.tools);
+        if (this.catalog) {
+            const verdict = verifyToolPins(this.catalog.pins, list.tools);
+            if (!verdict.ok) {
+                throw new DriftDetected(`tool catalog changed: ${verdict.reasons.join("; ")}`, this.receipt("catalog.refresh", this.dispatcher.usage(), "blocked", {
+                    note: verdict.reasons.join("; "),
+                }));
+            }
+        }
+        const snapshot = {
+            tools: list.tools,
+            digest: pins.catalog,
+            pins,
+            ttlMs: list.ttlMs,
+            expiresAt: Date.now() + list.ttlMs,
+        };
+        this.catalog = snapshot;
+        return snapshot;
+    }
+    async ensureFresh() {
+        if (!this.catalog) {
+            await this.connect();
+            return;
+        }
+        if (Date.now() < this.catalog.expiresAt) {
+            return;
+        }
+        await this.refresh();
+    }
+    tools() {
+        return this.catalog?.tools ?? [];
+    }
+    tool(name) {
+        return this.tools().find((tool) => tool.name === name);
+    }
+    /**
+     * Host-only convenience: issue an approval bound to the current tool schema
+     * and the exact arguments. The model must never be given this method.
+     */
+    approveTool(name, args, approvedBy, ttlMs, scope) {
+        const tool = this.tool(name);
+        if (!tool) {
+            throw new PolicyDenied(`unknown tool: ${name}`);
+        }
+        return this.policy.approve({
+            action: name,
+            effect: effectFor(tool),
+            approvedBy,
+            ttlMs,
+            scope,
+            toolDigest: digestTool(tool),
+            argsDigest: digestOf(args),
+        });
+    }
+    /**
+     * Non-throwing drift check for monitoring.
+     */
+    async verify() {
+        const list = await this.client.listTools();
+        const pins = pinTools(list.tools);
+        return {
+            ok: this.catalog !== (void 0) && pins.catalog === this.catalog.digest,
+            digest: pins.catalog,
+        };
+    }
+    async call(name, args, options = {}) {
+        await this.ensureFresh();
+        const tool = this.tool(name);
+        if (!tool) {
+            throw new PolicyDenied(`unknown tool: ${name}`, this.receipt(name, this.dispatcher.usage(), "blocked", { note: `unknown_tool:${name}` }));
+        }
+        if (this.verifyPinsAtCall) {
+            const fresh = await this.client.listTools();
+            const pinned = verifyToolPins(this.catalog?.pins ?? pinTools([]), fresh.tools);
+            if (!pinned.ok) {
+                const receipt = this.receipt(name, this.dispatcher.usage(), "blocked", {
+                    note: pinned.reasons.join("; "),
+                });
+                throw new DriftDetected(`tool changed before call: ${pinned.reasons.join("; ")}`, receipt);
+            }
+        }
+        let callArgs = args;
+        let argsDigest = digestOf(args);
+        if (this.validateArgs) {
+            try {
+                const parsed = parseToolCall({ name: tool.name, inputSchema: tool.inputSchema }, args);
+                callArgs = parsed.args;
+                argsDigest = parsed.digest;
+            }
+            catch (error) {
+                if (error instanceof BoundaryRejection) {
+                    const receipt = this.receipt(name, this.dispatcher.usage(), "blocked", {
+                        note: `invalid_tool_args:${error.problems.join("; ")}`,
+                    });
+                    throw new PolicyDenied(`invalid arguments for ${name}: ${error.problems.join("; ")}`, receipt);
+                }
+                throw error;
+            }
+        }
+        const effect = options.effect ?? effectFor(tool);
+        const verdict = this.policy.decide({
+            action: name,
+            target: { kind: "tool", id: `mcp.${name}` },
+            effect,
+            claim: options.claim,
+            toolDigest: digestTool(tool),
+            argsDigest,
+        }, options.approval);
+        if (verdict.outcome !== "allow") {
+            const receipt = this.receipt(name, this.dispatcher.usage(), "blocked", {
+                note: `${verdict.outcome}:${verdict.reason}`,
+            });
+            if (verdict.outcome === "approval_required") {
+                throw new ApprovalRequired(name, receipt, verdict.reason);
+            }
+            throw new PolicyDenied(`policy denied ${name}: ${verdict.reason}`, receipt);
+        }
+        try {
+            this.guard?.beforeDispatch({ money: options.money ?? 0 });
+        }
+        catch (error) {
+            const receipt = this.receipt(name, this.dispatcher.usage(), "blocked", {
+                note: error instanceof Error ? error.message : `${error}`,
+            });
+            throw new PolicyDenied(`guard blocked ${name}: ${`${error}`}`, receipt);
+        }
+        const budgetTokens = options.budgetTokens ?? this.maxResultTokens;
+        let text;
+        try {
+            const result = await this.dispatcher.run(() => this.client.callTool(name, callArgs), {
+                calls: 1,
+                ms: 900,
+            });
+            text = textOf(result);
+            this.guard?.recordSuccess();
+        }
+        catch (error) {
+            this.guard?.recordFailure();
+            this.receipt(name, this.dispatcher.usage(), "blocked", {
+                note: error instanceof BudgetExceeded ? `${error.code}:${error.dimension}` : `${error}`,
+            });
+            throw error;
+        }
+        const tokens = Math.ceil(text.length / 4);
+        if (tokens > budgetTokens) {
+            const handle = this.handles.put(text, "text", tokens);
+            const receipt = this.receipt(name, this.dispatcher.usage(), "success", {
+                handle,
+                predicted_voi: options.predictedVoi,
+                realized_voi: options.realizedVoi,
+                note: `result ${tokens} tokens > budget ${budgetTokens}; handle emitted, nothing truncated`,
+            });
+            return { receipt, handle: handle.id, tokens };
+        }
+        const receipt = this.receipt(name, this.dispatcher.usage(), "success", {
+            predicted_voi: options.predictedVoi,
+            realized_voi: options.realizedVoi,
+        });
+        return { receipt, inline: text, tokens };
+    }
+    receipt(tool, usage, outcome, extra = {}) {
+        this.seq += 1;
+        const receipt = {
+            amp: "0.1",
+            kind: "receipt",
+            id: `rc.exec.${this.seq}`,
+            op: "act",
+            target: { kind: "tool", id: `mcp.${tool}` },
+            at: this.now(),
+            usage,
+            outcome,
+            ...extra,
+        };
+        this.onReceipt?.(receipt);
+        return receipt;
+    }
+}

package/lib/execution/handles.d.ts

@@ -0,0 +1,25 @@
+import type { Handle } from "../types/common.js";
+export interface HandlePage {
+    text: string;
+    next: number | null;
+    totalPages: number;
+    tokens: number;
+}
+/**
+ * Content-addressed handle store.
+ *
+ * Handles are opaque names, not capabilities: possession of an id must not be
+ * sufficient to read it in a real host (scope + session binding live outside
+ * this reference implementation, see architecture §11.1 T5).
+ */
+export declare class HandleStore {
+    private records;
+    private seq;
+    put(content: string, kind: Handle["kind"], tokens: number, scope?: Handle["scope"], ttlMs?: number): Handle;
+    has(id: string): boolean;
+    get(id: string): Handle | undefined;
+    /**
+     * Deterministic paging: same cursor always returns the same window.
+     */
+    read(id: string, cursor: number, limitTokens?: number): HandlePage;
+}

package/lib/execution/handles.js

@@ -0,0 +1,45 @@
+import { sha256Hex } from "../semantic/sha256.js";
+const CharsPerToken = 4;
+/**
+ * Content-addressed handle store.
+ *
+ * Handles are opaque names, not capabilities: possession of an id must not be
+ * sufficient to read it in a real host (scope + session binding live outside
+ * this reference implementation, see architecture §11.1 T5).
+ */
+export class HandleStore {
+    records = new Map();
+    seq = 0;
+    put(content, kind, tokens, scope = "session", ttlMs = 900_000) {
+        this.seq += 1;
+        const id = `h.${sha256Hex(`${kind}:${this.seq}:${content.length}`).slice(0, 10)}`;
+        const handle = { id, kind, tokens, scope, ttl_ms: ttlMs };
+        this.records.set(id, { handle, content, createdAt: Date.now() });
+        return handle;
+    }
+    has(id) {
+        return this.records.has(id);
+    }
+    get(id) {
+        return this.records.get(id)?.handle;
+    }
+    /**
+     * Deterministic paging: same cursor always returns the same window.
+     */
+    read(id, cursor, limitTokens = 240) {
+        const record = this.records.get(id);
+        if (!record) {
+            throw new Error(`unknown handle: ${id}`);
+        }
+        const window = Math.max(1, limitTokens * CharsPerToken);
+        const start = Math.max(0, Math.min(cursor, record.content.length));
+        const end = Math.min(record.content.length, start + window);
+        const text = record.content.slice(start, end);
+        return {
+            text,
+            next: end < record.content.length ? end : null,
+            totalPages: Math.ceil(record.content.length / window),
+            tokens: Math.ceil(text.length / CharsPerToken),
+        };
+    }
+}

package/lib/execution/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./exec.js";
+export * from "./handles.js";
+export * from "./pin.js";

package/lib/execution/index.js

@@ -0,0 +1,3 @@
+export * from "./exec.js";
+export * from "./handles.js";
+export * from "./pin.js";

package/lib/execution/pin.d.ts

@@ -0,0 +1,60 @@
+import type { Digest } from "../types/common.js";
+import type { McpTool } from "../module/mcp/protocol.js";
+/**
+ * Per-tool catalog pinning.
+ *
+ * The whole-catalog digest in `ExecProfile` is useful for detecting a changed
+ * list, but it is checked at connect/refresh time. The TOCTOU window remains:
+ * a server can change one tool between that check and the moment its schema is
+ * used to validate arguments. These helpers make the pin explicit per tool so
+ * a host can re-assert it immediately before a call.
+ *
+ * `digestTool` covers the fields that influence what the model sees and what
+ * arguments are validated: name, title, description, input schema and
+ * annotations. It deliberately does not cover the MCP output schema, which is
+ * not used for input validation.
+ */
+export interface ToolPins {
+    /**
+     * Digest of the tool set, sorted by name.
+     *
+     * MCP only SHOULD return a deterministic order and AMP must not build a
+     * signature or cache on a server-controlled order (architecture §10.6), so
+     * reordering the same tools is not drift.
+     */
+    catalog: Digest;
+    /**
+     * Tool name to per-tool digest.
+     */
+    tools: ReadonlyMap<string, Digest>;
+}
+export interface PinVerdict {
+    ok: boolean;
+    reasons: string[];
+    /**
+     * Names whose digest changed, plus added/removed names.
+     */
+    changed: string[];
+}
+/**
+ * Stable digest of one tool, including its description and input schema.
+ */
+export declare const digestTool: (tool: McpTool) => Digest;
+/**
+ * Build a pin set from a `tools/list` result. Duplicate names fail closed.
+ */
+export declare const pinTools: (tools: readonly McpTool[]) => ToolPins;
+/**
+ * Compare a fresh tool list against a previous pin set.
+ *
+ * The catalog digest catches reordering/removals; per-tool comparison catches a
+ * changed description or schema even when the list shape is unchanged.
+ */
+export declare const verifyToolPins: (pins: ToolPins, tools: readonly McpTool[]) => PinVerdict;
+/**
+ * Assert that the requested tool is still exactly the pinned tool.
+ *
+ * A host can call this with the schema it is about to use for validation; an
+ * absent pin is a failure, never an implicit trust decision.
+ */
+export declare const assertToolPinned: (pins: ToolPins, tool: McpTool) => PinVerdict;

package/lib/execution/pin.js

@@ -0,0 +1,103 @@
+import { digestOf } from "../semantic/canonical.js";
+/**
+ * Stable digest of one tool, including its description and input schema.
+ */
+export const digestTool = (tool) => {
+    return digestOf({
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: tool.annotations ?? {},
+    });
+};
+/**
+ * Build a pin set from a `tools/list` result. Duplicate names fail closed.
+ */
+export const pinTools = (tools) => {
+    const pinned = new Map();
+    for (let i = 0; i < tools.length; i += 1) {
+        const tool = tools[i];
+        if (pinned.has(tool.name)) {
+            throw new Error(`duplicate tool name in catalog: ${tool.name}`);
+        }
+        pinned.set(tool.name, digestTool(tool));
+    }
+    return { catalog: catalogDigest(tools), tools: pinned };
+};
+/**
+ * Order-independent digest of a tool catalog.
+ */
+const catalogDigest = (tools) => {
+    const sorted = [...tools].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return digestOf(sorted);
+};
+/**
+ * Compare a fresh tool list against a previous pin set.
+ *
+ * The catalog digest catches reordering/removals; per-tool comparison catches a
+ * changed description or schema even when the list shape is unchanged.
+ */
+export const verifyToolPins = (pins, tools) => {
+    const reasons = [];
+    const changed = new Set();
+    const current = new Map();
+    for (let i = 0; i < tools.length; i += 1) {
+        const tool = tools[i];
+        if (current.has(tool.name)) {
+            reasons.push(`duplicate tool name: ${tool.name}`);
+            changed.add(tool.name);
+            continue;
+        }
+        current.set(tool.name, tool);
+    }
+    const pinnedTools = [...pins.tools];
+    for (let i = 0; i < pinnedTools.length; i += 1) {
+        const name = pinnedTools[i][0];
+        const digest = pinnedTools[i][1];
+        const tool = current.get(name);
+        if (!tool) {
+            reasons.push(`tool removed: ${name}`);
+            changed.add(name);
+            continue;
+        }
+        const next = digestTool(tool);
+        if (next !== digest) {
+            reasons.push(`tool changed: ${name} ${digest} -> ${next}`);
+            changed.add(name);
+        }
+    }
+    const currentNames = [...current.keys()];
+    for (let i = 0; i < currentNames.length; i += 1) {
+        const name = currentNames[i];
+        if (!pins.tools.has(name)) {
+            reasons.push(`tool added: ${name}`);
+            changed.add(name);
+        }
+    }
+    if (catalogDigest(tools) !== pins.catalog) {
+        reasons.push("catalog digest changed");
+    }
+    return { ok: reasons.length === 0, reasons, changed: [...changed].sort() };
+};
+/**
+ * Assert that the requested tool is still exactly the pinned tool.
+ *
+ * A host can call this with the schema it is about to use for validation; an
+ * absent pin is a failure, never an implicit trust decision.
+ */
+export const assertToolPinned = (pins, tool) => {
+    const expected = pins.tools.get(tool.name);
+    if (expected === (void 0)) {
+        return { ok: false, reasons: [`tool not pinned: ${tool.name}`], changed: [tool.name] };
+    }
+    const actual = digestTool(tool);
+    if (actual !== expected) {
+        return {
+            ok: false,
+            reasons: [`tool changed: ${tool.name} ${expected} -> ${actual}`],
+            changed: [tool.name],
+        };
+    }
+    return { ok: true, reasons: [], changed: [] };
+};

package/lib/frame/frame.d.ts

@@ -0,0 +1,61 @@
+/**
+ * AMP v0.1 — Frame (注意帧): one immutable allocation snapshot.
+ * Mirrors docs/schemas/frame.schema.json.
+ */
+import type { Budget, Confidence, Digest, Id, Ref, Tier, Timestamp, Usage } from "../types/common.js";
+export type FrameMode = "explore" | "exploit" | "triage" | "reflect" | "rest";
+export type SlotRole = "goal" | "question" | "evidence" | "concept" | "process" | "tool" | "memory" | "self" | "other" | "threat" | "artifact";
+export type IgnoredReason = "low_voi" | "out_of_scope" | "untrusted" | "budget" | "blocked" | "habituated" | "deferred";
+export type ImpasseState = "TIE" | "STUCK" | "STALLED" | "CONFLICT" | "INFEASIBLE" | "UNKNOWN" | "UNVERIFIED" | "DRIFT" | "BUDGET";
+/**
+ * Why something is being attended to — required, not decorative (A-1).
+ */
+export interface Slot {
+    target: Ref;
+    role: SlotRole;
+    tier?: Tier;
+    salience: Confidence;
+    voi?: Confidence;
+    cost: Budget;
+    budget?: Budget;
+    why: string;
+    ttl_turns?: number;
+    state: "active" | "released" | "evicted" | "done";
+}
+/**
+ * Deliberate exclusion. The distinctive field: no classical architecture records this.
+ */
+export interface Ignored {
+    target: Ref;
+    reason: IgnoredReason;
+    revisit_if: string;
+}
+export interface FrameBudget {
+    allocated: Budget;
+    spent: Usage;
+}
+export interface Impasse {
+    state: ImpasseState;
+    detail?: string;
+}
+export interface Frame {
+    amp: "0.1";
+    kind: "frame";
+    id: Id;
+    agent: Id;
+    cycle: number;
+    ts: Timestamp;
+    parent?: Ref;
+    digest: Digest;
+    mode: FrameMode;
+    goal?: Ref;
+    /**
+     * At most 9 slots. Capacity is the point, not a limitation.
+     */
+    slots: Slot[];
+    ignored?: Ignored[];
+    budget: FrameBudget;
+    open_questions?: Ref[];
+    impasse?: Impasse;
+    note?: string;
+}

package/lib/frame/frame.js

@@ -0,0 +1 @@
+export {};

package/lib/frame/index.d.ts

@@ -0,0 +1 @@
+export * from "./frame.js";

package/lib/frame/index.js

@@ -0,0 +1 @@
+export * from "./frame.js";

package/lib/goal/goal.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Goal lifecycle: the admission state machine for a `Goal`.
+ *
+ * A goal is not "active" because someone said so; it moves through explicit
+ * states, and `achieved`/`abandoned` are terminal. The plan and warrant layers
+ * read this state instead of inferring intent from prose.
+ */
+import type { Goal } from "./plan.js";
+export type GoalState = "proposed" | "committed" | "active" | "achieved" | "abandoned";
+export interface GoalLifecycle {
+    goal: Goal;
+    state: GoalState;
+    startedAt?: string;
+    achievedAt?: string;
+}
+export declare const createGoalLifecycle: (goal: Goal) => GoalLifecycle;
+type TransitionGoal = (lifecycle: GoalLifecycle, to: GoalState, at: string) => GoalLifecycle;
+export declare const transitionGoal: TransitionGoal;
+export {};

package/lib/goal/goal.js

@@ -0,0 +1,21 @@
+const GoalEdges = {
+    proposed: ["committed", "abandoned"],
+    committed: ["active", "abandoned"],
+    active: ["achieved", "abandoned"],
+    achieved: [],
+    abandoned: [],
+};
+export const createGoalLifecycle = (goal) => ({ goal, state: "proposed" });
+export const transitionGoal = (lifecycle, to, at) => {
+    if (!GoalEdges[lifecycle.state].includes(to)) {
+        throw new Error(`goal ${lifecycle.goal.id}: ${lifecycle.state} -> ${to} is not an edge`);
+    }
+    const next = { ...lifecycle, state: to };
+    if (to === "active" && next.startedAt === (void 0)) {
+        next.startedAt = at;
+    }
+    if (to === "achieved") {
+        next.achievedAt = at;
+    }
+    return next;
+};

package/lib/goal/index.d.ts

@@ -0,0 +1,2 @@
+export { createGoalLifecycle, transitionGoal } from "./goal.js";
+export type { GoalLifecycle, GoalState } from "./goal.js";

package/lib/goal/index.js

@@ -0,0 +1 @@
+export { createGoalLifecycle, transitionGoal } from "./goal.js";