@finchip.ai/foga 0.0.0-stage → 0.6.0-alpha.4

package/dist/node/policy.js

@@ -0,0 +1,95 @@
+export const ok = (gate, reason) => ({ gate, ok: true, reason });
+export const refused = (gate, reason) => ({ gate, ok: false, reason });
+/** The first refusal, or null when every gate passed. */
+export function firstRefusal(gates) {
+    return gates.find((g) => !g.ok) ?? null;
+}
+/** The policy block of a cell applied to one tender: reward, deadlines, state, verifier, counterparty. */
+export function tenderGates(cfg, t, clock, dir) {
+    const p = cfg.policy.tenders;
+    const gates = [];
+    const minReward = BigInt(p.minRewardWei);
+    // reward and state
+    if (t.asset !== "0x0000000000000000000000000000000000000000")
+        gates.push(refused("policy", `the reward is paid in ${t.asset}; the cell takes native-asset tenders only`));
+    else if (t.rewardWei < minReward)
+        gates.push(refused("policy", `reward ${t.rewardWei} wei is below the policy floor ${minReward} wei`));
+    else
+        gates.push(ok("policy", `reward ${t.rewardWei} wei meets the floor ${minReward} wei`));
+    if (t.cancelled)
+        gates.push(refused("policy", "the tender is cancelled"));
+    if (t.maxCompletions !== 0n && t.completions >= t.maxCompletions)
+        gates.push(refused("policy", `the tender has its ${t.maxCompletions} completion(s) already`));
+    if (t.escrowWei < t.rewardWei)
+        gates.push(refused("policy", `escrow ${t.escrowWei} wei does not cover the reward ${t.rewardWei} wei`));
+    // deadlines: enough time left to submit and to settle
+    const submitLeft = t.submitBy === 0n ? null : Number(t.submitBy) - clock.now;
+    const settleLeft = t.settleBy === 0n ? null : Number(t.settleBy) - clock.now;
+    const deadlines = [];
+    if (submitLeft !== null && submitLeft < p.minSubmitWindowSeconds)
+        deadlines.push(refused("policy", submitLeft <= 0 ? "past submitBy" : `only ${submitLeft} s left to submit; the policy wants ${p.minSubmitWindowSeconds} s`));
+    if (settleLeft !== null && settleLeft < p.minSettleWindowSeconds)
+        deadlines.push(refused("policy", settleLeft <= 0 ? "past settleBy" : `only ${settleLeft} s left to settle; the policy wants ${p.minSettleWindowSeconds} s`));
+    gates.push(...(deadlines.length ? deadlines : [ok("policy", `deadlines open (submitBy ${submitLeft === null ? "none" : `in ${submitLeft} s`}, settleBy ${settleLeft === null ? "none" : `in ${settleLeft} s`})`)]));
+    // the acceptance authority the cell works under
+    const resolveName = (a) => (a === "hashlock" ? dir.hashlock : a);
+    const match = p.acceptance.find((a) => resolveName(a).toLowerCase() === t.acceptanceAuthority.toLowerCase());
+    if (!match)
+        gates.push(refused("verifier", `acceptance authority ${t.acceptanceAuthority} is not one the cell works under (${p.acceptance.join(", ")})`));
+    else if (match === "hashlock" && t.acceptanceProfile && t.acceptanceProfile !== "x-hashlock-v1")
+        gates.push(refused("verifier", `the task document names acceptance profile ${t.acceptanceProfile}; the hashlock verifier settles x-hashlock-v1 only`));
+    else
+        gates.push(ok("verifier", `acceptance authority ${t.acceptanceAuthority} (${match})`));
+    // the counterparty's standing, when the policy asks for it
+    if (p.counterpartyMinLevel > 0) {
+        if (t.counterpartyLevel === null)
+            gates.push(refused("policy", `the policy requires the demander at KYA level ${p.counterpartyMinLevel} and no level could be read`));
+        else if (t.counterpartyLevel < p.counterpartyMinLevel)
+            gates.push(refused("policy", `the demander's KYA level ${t.counterpartyLevel} is below the required ${p.counterpartyMinLevel}`));
+        else
+            gates.push(ok("policy", `demander at KYA level ${t.counterpartyLevel} (required ${p.counterpartyMinLevel})`));
+    }
+    return gates;
+}
+/** Whether the cell holds and offers the skill a tender asks for, with the package the chain commits to. */
+export function skillGate(cfg, t, held) {
+    if (!t.skill)
+        return refused("skill", "the task document names no skill (foga.task/1 expected)");
+    const have = held.find((h) => h.name === t.skill);
+    if (!have)
+        return refused("skill", `the cell holds no skill named ${t.skill} (held: ${held.map((h) => h.name).join(", ") || "none"})`);
+    if (!cfg.skills.offered.includes(t.skill))
+        return refused("skill", `the cell holds ${t.skill} but does not offer it (policy: offered = ${cfg.skills.offered.join(", ") || "none"})`);
+    if (t.packageHash && t.packageHash.toLowerCase() !== have.packageHash.toLowerCase())
+        return refused("skill", `the task wants package ${t.packageHash.slice(0, 10)}… of ${t.skill}; the cell's token commits to ${have.packageHash.slice(0, 10)}…`);
+    return ok("skill", `${t.skill} held and offered; package ${have.packageHash.slice(0, 10)}… matches the token's commitment`);
+}
+/** Liveness and safety: the anchor must be ACTIVE and the binding Satisfied for a commitment; de-risk actions pass under a derisk-only suspension. */
+export function safetyGate(aidState, status, kind) {
+    if (kind === "commitment" && aidState !== "ACTIVE")
+        return refused("safety", `anchor ${aidState}: no commitment-class call while not ACTIVE`);
+    if (status.verdictName === "Satisfied")
+        return ok("safety", `anchor ${aidState}, binding Satisfied`);
+    const stopped = status.reasonNames.filter((r) => r === "Suspended" || r === "StoppedByIntervener" || r === "Terminated");
+    if (kind === "derisk" && status.verdictName === "NotSatisfied" && stopped.length && !status.restrictions.includes(16))
+        return ok("safety", `binding ${status.verdictName} [${status.reasonNames.join(",")}]: a de-risk action, allowed under the suspension`);
+    return refused("safety", `binding ${status.verdictName} [${status.reasonNames.join(",")}]${status.restrictions.length ? `, restrictions ${status.restrictions.join(",")}` : ""}`);
+}
+/** The four books of the budget (value, gas, model, resources; the first two here) against a request. */
+export function budgetGate(cfg, use, req) {
+    const b = cfg.policy.budget;
+    const perOp = BigInt(b.perOperationValueWei);
+    const dailyValue = BigInt(b.dailyValueWei);
+    const dailyGas = BigInt(b.dailyGasWei);
+    if (req.valueWei > perOp)
+        return refused("budget", `the operation would move ${req.valueWei} wei; the per-operation cap is ${perOp} wei`);
+    const valueAfter = use.valueWei + use.reservedValueWei + req.valueWei;
+    if (valueAfter > dailyValue)
+        return refused("budget", `value moved and reserved in the last 24 h would reach ${valueAfter} wei; the daily cap is ${dailyValue} wei`);
+    const gasAfter = use.gasWei + use.reservedFeeWei + req.feeReserveWei;
+    if (gasAfter > dailyGas)
+        return refused("budget", `fees paid and reserved in the last 24 h would reach ${gasAfter} wei; the daily cap is ${dailyGas} wei`);
+    if (req.commitment && use.runningCommitments >= b.maxConcurrentCommitments)
+        return refused("budget", `${use.runningCommitments} commitment(s) open; the policy allows ${b.maxConcurrentCommitments} at a time`);
+    return ok("budget", `value ${valueAfter}/${dailyValue} wei, fees ${gasAfter}/${dailyGas} wei in the window${req.commitment ? `, commitments ${use.runningCommitments + 1}/${b.maxConcurrentCommitments}` : ""}`);
+}

package/dist/node/runner.js

@@ -0,0 +1,256 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { jcs, sha256Hex } from "../core/canonical.js";
+import { chooseTender } from "./model/stub.js";
+import { ModelError } from "./model/types.js";
+/** The model's proposals arrive through this caller: act level, the operator's view, entrance `runner`. */
+export const RUNNER_CALLER = { id: "runner", entrance: "runner", level: "act", visibility: "operator" };
+/** The key under which the runner counts the model calls of one UTC day. */
+export const modelCallsKey = (day = new Date().toISOString().slice(0, 10)) => `runner.model.calls.${day}`;
+const JOURNAL_SEQ_FACT = "runner.journal.seq";
+/**
+ * The runner (design memo, Phase 3, section 8): the node's loop with a model in it. Each tick perceives through the
+ * read capabilities, hands the situation and the capability catalog to the model as tools, carries out what it
+ * proposes — reads at once, acts through `Catalog.invoke` where the three checks decide — gives the result or the
+ * refusal back so the model can revise, and records the tick: the decision records the catalog wrote, the hash of
+ * the whole transcript, and the counts. Limits bound a tick (tool calls, acts, the day's model calls); nothing a
+ * model says reaches the chain except through the catalog, and nothing it says is kept except by hash. The watchers
+ * (heartbeat, settlement, withdrawal, discovery) do not pass through the model; they run beside the runner.
+ */
+export class Runner {
+    node;
+    catalog;
+    adapter;
+    opts;
+    maxToolCalls;
+    maxActs;
+    log;
+    ticks = 0;
+    constructor(node, catalog, adapter, opts = {}) {
+        this.node = node;
+        this.catalog = catalog;
+        this.adapter = adapter;
+        this.opts = opts;
+        this.maxToolCalls = opts.maxToolCallsPerTick ?? node.config.runtime.model.maxToolCallsPerTick;
+        this.maxActs = opts.maxActsPerTick ?? node.config.runtime.model.maxActsPerTick;
+        this.log = opts.log ?? node.log;
+    }
+    /** The tools the model gets: the reads and the acts of the catalog as this caller sees them (no admin, no build or dry-run variants). */
+    tools() {
+        return this.catalog
+            .list(RUNNER_CALLER)
+            .filter((c) => c.action === "read" || (c.action === "act" && c.modes.includes("act")))
+            .map((c) => ({ name: c.name, description: c.description, inputSchema: c.inputSchema }));
+    }
+    /** What the model is told once per tick, before the situation. */
+    system() {
+        const cfg = this.node.config;
+        return [
+            `You are the runner of FOGA cell ${cfg.name} (account ${this.node.body.address}), an agent on the ten-ERC stack. You decide which open ERC-8414 tenders the cell takes and carry them through: tender_inspect, tender_precheck (eligible: false names the gate that refuses), skill_run with the task's input, tender_submit with the run's resultHash and runReceipt, tender_settle with the run's answer, credit_withdraw when a settlement credited rather than paid.`,
+            `Every act you propose is judged by the cell's catalog: permission, the policy below, the budget, the account's own gate. A refusal (ok: false, gate, reason, decisionId) is the cell's verdict; do not look for a way around it and do not retry the same act with cosmetic changes. A tender whose status is failed (a run or a submission of the cell's failed) answers with that failure; leave it. Reads are free; acts are limited per tick (the situation says how many). Say briefly what you are doing and why; stop when there is nothing left to decide.`,
+            `The cell's policy (what it takes and how much it may move): ${JSON.stringify(cfg.policy)}.`,
+        ].join("\n");
+    }
+    /** The situation of this tick, composed from the read capabilities and the store. */
+    async situation() {
+        const node = this.node;
+        const k = node.kernel;
+        const cell = node.body.address;
+        const invoke = (name, input = {}) => this.catalog.invoke(node, name, input, RUNNER_CALLER);
+        const [block, statusR, listR, anchor] = await Promise.all([k.blockNumber(), invoke("cell_status"), invoke("tender_list"), k.aid.stateName(cell)]);
+        const status = statusR.ok ? statusR.output : null;
+        const decisions = node.store.decisions({ limit: 5000 });
+        const runnerPrechecks = decisions.filter((d) => d.caller === RUNNER_CALLER.id && d.capability === "tender_precheck");
+        const jobs = node.store.jobs(null, 5000);
+        const runs = jobs.filter((j) => j.kind === "skill-run" && j.status === "done");
+        const held = await node.heldSkills().catch(() => []);
+        const tenders = [];
+        if (listR.ok) {
+            const open = listR.output.tenders.filter((t) => t.demander.toLowerCase() !== cell.toLowerCase());
+            for (const t of open.slice(0, 20)) {
+                const r = await invoke("tender_inspect", { tokenId: t.tokenId });
+                if (!r.ok)
+                    continue;
+                const v = r.output;
+                const mine = v.submissions.filter((s) => s.fulfiller.toLowerCase() === cell.toLowerCase()).at(-1) ?? null;
+                const credit = await k.tenders.creditOf(BigInt(t.tokenId), cell).catch(() => 0n);
+                let st = "open";
+                let gate;
+                let reason;
+                const failedJob = jobs.find((j) => j.status === "failed" && ((j.kind === "skill-run" && String(j.input?.tokenId) === t.tokenId) || (j.kind === "tender" && j.id.startsWith(`tender:${t.tokenId}:`))));
+                if (mine && mine.status === 1)
+                    st = "settled";
+                else if (mine && mine.status === 0)
+                    st = "submitted";
+                else if (failedJob) {
+                    st = "failed";
+                    gate = "execution";
+                    reason = `${failedJob.kind} ${failedJob.id} failed: ${(failedJob.error ?? "no reason recorded").slice(0, 200)}`;
+                }
+                else {
+                    const last = runnerPrechecks.filter((d) => d.jobId === `precheck:${t.tokenId}`).at(-1);
+                    if (last?.verdict === "allowed")
+                        st = "eligible";
+                    else if (last) {
+                        st = "refused";
+                        gate = last.gate;
+                        reason = last.reason;
+                    }
+                }
+                const answer = mine ? (runs.find((j) => j.result?.resultHash?.toLowerCase() === mine.resultHash.toLowerCase())?.result?.answer ?? null) : null;
+                tenders.push({
+                    tokenId: v.tokenId,
+                    demander: v.demander,
+                    rewardWei: v.rewardWei,
+                    escrowWei: v.escrowWei,
+                    submitBy: v.submitBy,
+                    settleBy: v.settleBy,
+                    completions: v.completions,
+                    maxCompletions: v.maxCompletions,
+                    acceptanceAuthority: v.acceptanceAuthority,
+                    task: v.task ? { skill: v.task.skill, packageHash: v.task.packageHash, input: v.task.input, acceptance: v.task.acceptance } : null,
+                    status: st,
+                    ...(gate ? { gate, reason } : {}),
+                    submission: mine ? { submissionId: mine.id, status: mine.status, resultHash: mine.resultHash, answer } : null,
+                    creditWei: credit.toString(),
+                });
+            }
+        }
+        const since = node.store.getFact(JOURNAL_SEQ_FACT) ?? 0;
+        const events = node.store
+            .journalEntries()
+            .filter((e) => e.seq > since && (e.event === "tender-discovered" || e.event === "safety-changed"))
+            .map((e) => ({ seq: e.seq, at: e.at, event: e.event, detail: e.detail }));
+        const use = node.budgetUse();
+        const cfg = node.config;
+        return {
+            at: new Date().toISOString(),
+            block,
+            chainId: node.chainId,
+            cell: { name: cfg.name, account: cell, operator: cfg.identity.operator, anchor, safety: status?.safety ?? { verdict: "unknown", reasons: [] } },
+            budget: {
+                dailyValueWei: cfg.policy.budget.dailyValueWei,
+                perOperationValueWei: cfg.policy.budget.perOperationValueWei,
+                dailyGasWei: cfg.policy.budget.dailyGasWei,
+                maxConcurrentCommitments: cfg.policy.budget.maxConcurrentCommitments,
+                valueWei: use.valueWei.toString(),
+                gasWei: use.gasWei.toString(),
+                reservedValueWei: use.reservedValueWei.toString(),
+                reservedFeeWei: use.reservedFeeWei.toString(),
+                runningCommitments: use.runningCommitments,
+                model: { callsToday: this.modelCallsToday(), dailyCalls: cfg.runtime.model.dailyCalls },
+            },
+            policy: cfg.policy.tenders,
+            skills: { held: held.map((h) => ({ name: h.name, packageHash: h.packageHash })), offered: cfg.skills.offered },
+            tenders,
+            events,
+            // the last forty, plus the runner's own mints however old (the stub's one-time over-budget proposal is recognized by its record)
+            recentDecisions: [...decisions.filter((d) => d.caller === RUNNER_CALLER.id && d.capability === "tender_mint" && !decisions.slice(-40).includes(d)), ...decisions.slice(-40)].map((d) => ({ id: d.id, at: d.at, caller: d.caller, capability: d.capability, mode: d.mode, verdict: d.verdict, gate: d.gate, reason: d.reason, jobId: d.jobId })),
+            limits: { toolCalls: this.maxToolCalls, acts: this.maxActs },
+        };
+    }
+    modelCallsToday() {
+        return this.node.store.getFact(modelCallsKey()) ?? 0;
+    }
+    countModelCall() {
+        const key = modelCallsKey();
+        this.node.store.setFact(key, (this.node.store.getFact(key) ?? 0) + 1);
+    }
+    /** One tick: perceive, propose, decide, execute, record. */
+    async tick() {
+        const node = this.node;
+        this.ticks++;
+        const situation = await this.situation();
+        const lastSeq = Math.max(node.store.getFact(JOURNAL_SEQ_FACT) ?? 0, ...situation.events.map((e) => e.seq));
+        const report = { at: situation.at, block: situation.block, skipped: null, modelCalls: 0, toolCalls: 0, acts: 0, decisions: [], refusals: [], trajectoryHash: null, error: null, tenders: situation.tenders.map((t) => ({ tokenId: t.tokenId, status: t.status, ...(t.gate ? { gate: t.gate } : {}) })) };
+        // event-driven: the model is called when something asks for a decision — an actionable tender or a new event
+        if (!chooseTender(situation) && situation.events.length === 0) {
+            report.skipped = "nothing to propose";
+            node.store.setFact(JOURNAL_SEQ_FACT, lastSeq);
+            return report;
+        }
+        if (situation.budget.model.callsToday >= situation.budget.model.dailyCalls) {
+            report.skipped = `the day's ${situation.budget.model.dailyCalls} model calls are spent`;
+            node.store.journal("runner-skipped", { at: situation.at, block: situation.block, reason: report.skipped });
+            node.store.setFact(JOURNAL_SEQ_FACT, lastSeq);
+            return report;
+        }
+        const system = this.system();
+        const tools = this.tools();
+        const offered = new Set(tools.map((t) => t.name));
+        const messages = [{ role: "user", content: [{ type: "text", text: JSON.stringify(situation) }] }];
+        const maxRounds = this.maxToolCalls + 2;
+        try {
+            for (let round = 0; round < maxRounds; round++) {
+                const request = { system, messages, tools };
+                const promptHash = sha256Hex(jcs(request));
+                this.countModelCall();
+                report.modelCalls++;
+                const res = await this.adapter.propose(request);
+                const responseHash = sha256Hex(jcs(res.content));
+                messages.push({ role: "assistant", content: res.content });
+                const uses = res.content.filter((b) => b.type === "tool_use");
+                if (uses.length === 0)
+                    break;
+                const results = [];
+                for (const use of uses) {
+                    const answer = (content, isError = false) => {
+                        results.push({ type: "tool_result", tool_use_id: use.id, content: typeof content === "string" ? content : JSON.stringify(content, (_k, v) => (typeof v === "bigint" ? v.toString() : v)), ...(isError ? { is_error: true } : {}) });
+                    };
+                    if (!offered.has(use.name)) {
+                        answer({ ok: false, gate: "permission", reason: `${use.name} is not a tool of this runner` }, true);
+                        continue;
+                    }
+                    if (report.toolCalls >= this.maxToolCalls) {
+                        answer({ ok: false, gate: "limit", reason: `this tick's ${this.maxToolCalls} tool calls are used; the rest waits for the next tick` }, true);
+                        continue;
+                    }
+                    report.toolCalls++;
+                    const cap = this.catalog.get(use.name);
+                    if (cap.action === "read") {
+                        const r = await this.catalog.invoke(node, use.name, use.input, RUNNER_CALLER);
+                        answer(r.ok ? r.output : { ok: false, gate: r.gate, reason: r.reason }, !r.ok);
+                        continue;
+                    }
+                    const counted = use.name !== "tender_precheck";
+                    if (counted && report.acts >= this.maxActs) {
+                        answer({ ok: false, gate: "limit", reason: `this tick's ${this.maxActs} acts are used; the rest waits for the next tick` }, true);
+                        continue;
+                    }
+                    if (counted)
+                        report.acts++;
+                    const r = await this.catalog.invoke(node, use.name, use.input, RUNNER_CALLER, { mode: "act", model: { provider: this.adapter.provider, model: this.adapter.model, promptHash, responseHash } });
+                    if (r.decisionId !== undefined)
+                        report.decisions.push(r.decisionId);
+                    if (use.name === "tender_precheck") {
+                        answer(r.ok ? { eligible: true, decisionId: r.decisionId ?? null, result: r.output } : { eligible: false, gate: r.gate, reason: r.reason, decisionId: r.decisionId ?? null });
+                        if (!r.ok)
+                            report.refusals.push({ capability: use.name, gate: r.gate, reason: r.reason });
+                        continue;
+                    }
+                    if (r.ok)
+                        answer({ ok: true, decisionId: r.decisionId ?? null, jobId: r.jobId ?? null, operations: r.operations ?? [], output: r.output });
+                    else {
+                        report.refusals.push({ capability: use.name, gate: r.gate, reason: r.reason });
+                        answer({ ok: false, gate: r.gate, reason: r.reason, decisionId: r.decisionId ?? null, jobId: r.jobId ?? null }, true);
+                    }
+                }
+                messages.push({ role: "user", content: results });
+            }
+        }
+        catch (e) {
+            report.error = e instanceof ModelError ? `model: ${e.message}` : e.message;
+            this.log(`runner: ${report.error}`);
+            node.store.journal("runner-model-error", { at: situation.at, block: situation.block, provider: this.adapter.provider, model: this.adapter.model, message: report.error });
+        }
+        report.trajectoryHash = sha256Hex(jcs({ system, tools: tools.map((t) => t.name), messages }));
+        node.store.journal("runner-tick", { at: situation.at, block: situation.block, provider: this.adapter.provider, model: this.adapter.model, modelCalls: report.modelCalls, toolCalls: report.toolCalls, acts: report.acts, decisions: report.decisions, refusals: report.refusals, trajectoryHash: report.trajectoryHash, tenders: report.tenders, error: report.error });
+        node.store.setFact(JOURNAL_SEQ_FACT, lastSeq);
+        if (this.opts.transcriptsDir) {
+            mkdirSync(this.opts.transcriptsDir, { recursive: true });
+            writeFileSync(join(this.opts.transcriptsDir, `${situation.at.replace(/[:.]/g, "-")}-tick-${String(this.ticks).padStart(4, "0")}.json`), JSON.stringify({ at: situation.at, system, tools: tools.map((t) => t.name), messages, report }, null, 2));
+        }
+        this.log(`runner tick ${this.ticks} at block ${report.block}: ${report.modelCalls} model call(s), ${report.toolCalls} tool call(s), ${report.acts} act(s), decisions [${report.decisions.join(", ")}]${report.refusals.length ? `, refused at ${report.refusals.map((r) => `${r.capability}:${r.gate}`).join(", ")}` : ""}; trajectory ${report.trajectoryHash.slice(0, 18)}…`);
+        return report;
+    }
+}

package/dist/node/watchers.js

@@ -0,0 +1,88 @@
+/** The node acting for itself: the watchers propose nothing to a model and need no key beyond the operator's. */
+export const WATCHER_CALLER = { id: "watcher", entrance: "runner", level: "act", visibility: "operator" };
+/**
+ * The watchers (design memo, Phase 3, section 2): what a node does without being asked and without a model —
+ * keep the anchor alive, notice new tenders, finish what it committed to once the chain lets it (settle a pending
+ * submission whose answer it holds, withdraw credited reward), and record a change of its safety state. Each duty
+ * goes through the catalog like any caller, so it passes the same gates and leaves the same records. `tick` runs
+ * every duty once; the serve loop (3b) calls it on the poll interval.
+ */
+export class Watchers {
+    node;
+    catalog;
+    constructor(node, catalog) {
+        this.node = node;
+        this.catalog = catalog;
+    }
+    async tick() {
+        const node = this.node;
+        const k = node.kernel;
+        const cell = node.body;
+        const block = await k.blockNumber();
+        const now = await node.now();
+        // 1. liveness: heartbeat when less than half the window is left
+        const anchor = await k.aid.stateName(cell.address);
+        let heartbeat = { sent: false, reason: `anchor ${anchor}` };
+        if (anchor === "ACTIVE" || anchor === "STALE") {
+            const [window, lastSeen] = await Promise.all([k.aid.livenessWindow(cell.address), k.aid.lastSeen(cell.address)]);
+            const left = Number(lastSeen) + window - now;
+            if (anchor === "STALE" || left < window / 2) {
+                const r = await this.catalog.invoke(node, "aid_heartbeat", { jobId: `heartbeat:${Math.floor(now / Math.max(60, Math.floor(window / 2)))}` }, WATCHER_CALLER);
+                heartbeat = r.ok ? { sent: true, reason: `${left} s of ${window} s left` } : { sent: false, reason: `${r.gate}: ${r.reason}` };
+            }
+            else
+                heartbeat = { sent: false, reason: `${left} s of ${window} s left` };
+        }
+        // 2. discovery: open tenders not seen before are recorded as facts for the runner (3c) and reported
+        const discovered = [];
+        const list = await this.catalog.invoke(node, "tender_list", {}, WATCHER_CALLER);
+        if (list.ok) {
+            for (const t of list.output.tenders) {
+                if (t.demander.toLowerCase() === cell.address.toLowerCase())
+                    continue;
+                const key = `watch.tender.${t.tokenId}`;
+                if (k.fact(key) === undefined) {
+                    k.setFact(key, { seenAt: now, block, rewardWei: t.rewardWei, demander: t.demander });
+                    k.store.journal("tender-discovered", { tokenId: t.tokenId, demander: t.demander, rewardWei: t.rewardWei, block });
+                    discovered.push(t.tokenId);
+                }
+            }
+        }
+        // 3. completion: a pending submission of the cell whose answer a skill run holds is settled; credited reward is withdrawn
+        const settled = [];
+        const withdrawn = [];
+        const jobs = k.store.jobs(null, 1000);
+        const runs = jobs.filter((j) => j.kind === "skill-run" && j.status === "done");
+        for (const job of jobs.filter((j) => j.kind === "tender" && j.status === "done")) {
+            const result = job.result;
+            if (!result?.tokenId || result.submissionId === undefined)
+                continue;
+            const tokenId = BigInt(result.tokenId);
+            const sub = await k.tenders.submissionOf(tokenId, BigInt(result.submissionId)).catch(() => null);
+            if (!sub)
+                continue;
+            if (sub.status === 0) {
+                const run = runs.find((r) => r.result?.resultHash?.toLowerCase() === sub.resultHash.toLowerCase());
+                const answer = run?.result?.answer;
+                if (!answer)
+                    continue;
+                const r = await this.catalog.invoke(node, "tender_settle", { tokenId: result.tokenId, submissionId: result.submissionId, answer, jobId: `${job.id}:settle` }, WATCHER_CALLER);
+                settled.push({ tokenId: result.tokenId, submissionId: result.submissionId, outcome: r.ok ? "settled" : `${r.gate}: ${r.reason}` });
+            }
+            const credit = await k.tenders.creditOf(tokenId, cell.address);
+            if (credit > 0n) {
+                const r = await this.catalog.invoke(node, "credit_withdraw", { tokenId: result.tokenId, jobId: `${job.id}:withdraw:${credit}` }, WATCHER_CALLER);
+                withdrawn.push({ tokenId: result.tokenId, outcome: r.ok ? `withdrew ${credit} wei` : `${r.gate}: ${r.reason}` });
+            }
+        }
+        // 4. safety: a change of verdict is journaled (the decision records show what it stopped)
+        const status = await cell.status();
+        const last = k.fact("watch.safety");
+        const changed = !last || last.verdict !== status.verdictName;
+        if (changed) {
+            k.setFact("watch.safety", { verdict: status.verdictName, reasons: status.reasonNames, at: now });
+            k.store.journal("safety-changed", { from: last?.verdict ?? null, to: status.verdictName, reasons: status.reasonNames, restrictions: status.restrictions, block });
+        }
+        return { at: new Date().toISOString(), block, heartbeat, discovered, settled, withdrawn, safety: { verdict: status.verdictName, reasons: status.reasonNames, changed }, anchor };
+    }
+}

package/dist/tools/admin.js

@@ -0,0 +1,184 @@
+import { getAddress } from "ethers";
+import { z } from "zod";
+import { BindingStateName, Restriction } from "../core/asf.js";
+import { keccakJcs } from "../core/canonical.js";
+import { ok, refused } from "../node/policy.js";
+import { derivedJobId, zAddress, zBytes32, zJobId, zUint } from "./common.js";
+/**
+ * Admin capabilities: the owner's and the guardian's acts (design memo, Phase 3, section 3 — admin is CLI-only in
+ * Phase 3). They need the owner's or the guardian's key loaded for the one run (`foga cell owner …`,
+ * `foga cell guardian …`); a node process holding the operator key alone refuses them at the permission gate. Their
+ * transactions are the signer's own (`route: direct`), not the cell's, except `identity_transfer`, which moves an
+ * asset through the account and is therefore the owner's `execute`.
+ */
+export const operator_rotate = {
+    name: "operator_rotate",
+    title: "Rotate the operator",
+    description: "The owner sets a new operator key (address, optional expiry and daily native-value cap) on the account; the allow-list stays, and the configuration records the new operator.",
+    action: "admin",
+    visibility: "operator",
+    principal: "cell",
+    signer: "owner",
+    ercs: [8468],
+    input: z.object({ operator: zAddress, validUntil: z.coerce.number().int().min(0).default(0), dailyValueCapWei: zUint.default("10000000000000000"), jobId: zJobId }),
+    output: z.object({ operator: zAddress, previous: zAddress, txHash: z.string(), jobId: z.string() }),
+    async plan({ node }, input) {
+        const cell = node.body;
+        const previous = await cell.operator();
+        const gates = [];
+        if (getAddress(previous) === getAddress(input.operator))
+            gates.push(refused("input", `${input.operator} is the operator already`));
+        else
+            gates.push(ok("policy", `operator ${previous} -> ${input.operator}`));
+        const jobId = input.jobId ?? derivedJobId("operator-rotate", { operator: input.operator, previous });
+        return {
+            job: { id: jobId, kind: "admin", input: { operator: input.operator, validUntil: input.validUntil, dailyValueCapWei: input.dailyValueCapWei } },
+            gates,
+            valueWei: 0n,
+            steps: [{ name: "setOperator", by: "owner", route: "direct", build: () => ({ target: cell.address, value: 0n, data: cell.iface.encodeFunctionData("setOperator", [input.operator, input.validUntil, BigInt(input.dailyValueCapWei)]), label: `setOperator(${input.operator})` }) }],
+            output: (confirmed) => {
+                node.config.identity.operator = getAddress(input.operator);
+                node.saveConfig();
+                return { operator: getAddress(input.operator), previous: getAddress(previous), txHash: confirmed[0].txHash, jobId };
+            },
+        };
+    },
+};
+const RESTRICTIONS = Object.keys(Restriction);
+export const guardian_suspend = {
+    name: "guardian_suspend",
+    title: "Suspend the cell's binding",
+    description: "The guardian (the binding's intervener) suspends the cell's presented binding in the ERC-8468 Binding Registry with the given restrictions; commitment-class calls stop at the account's gate, de-risk actions stay open under deriskOnly.",
+    action: "admin",
+    visibility: "operator",
+    principal: "cell",
+    signer: "guardian",
+    ercs: [8468],
+    input: z.object({ restrictions: z.array(z.enum(RESTRICTIONS)).default(["noNewRisk", "deriskOnly"]), reason: z.string().min(1).max(500), response: z.string().max(500).default("no new commitments; de-risk actions continue; wait for resume"), jobId: zJobId }),
+    output: z.object({ bindingId: zBytes32, restrictions: z.number(), state: z.string(), txHash: z.string(), jobId: z.string() }),
+    async plan({ node }, input) {
+        const k = node.kernel;
+        const bindingId = node.config.identity.bindingId;
+        const gates = [];
+        if (!bindingId)
+            gates.push(refused("input", "the configuration names no binding (identity.bindingId)"));
+        const mask = input.restrictions.reduce((m, r) => m | Restriction[r], 0);
+        let state = "None";
+        if (bindingId) {
+            const b = await k.asf.bindingOf(bindingId);
+            state = BindingStateName[b.state] ?? String(b.state);
+            if (state !== "Active")
+                gates.push(refused("policy", `binding ${bindingId.slice(0, 10)}… is ${state}, not Active`));
+            else
+                gates.push(ok("policy", `binding ${bindingId.slice(0, 10)}… Active; restrictions ${input.restrictions.join("|")} (${mask})`));
+        }
+        const jobId = input.jobId ?? derivedJobId("guardian-suspend", { bindingId, mask, reason: input.reason, at: Math.floor(Date.now() / 1000) });
+        const reasonRef = keccakJcs({ kind: "reason", summary: input.reason });
+        const responseRef = keccakJcs({ kind: "response", summary: input.response });
+        return {
+            job: { id: jobId, kind: "admin", input: { bindingId, restrictions: input.restrictions, reason: input.reason } },
+            gates,
+            valueWei: 0n,
+            steps: [{ name: "suspend", by: "guardian", route: "direct", build: () => ({ target: k.asf.bindingRegistryAddress, value: 0n, data: k.asf.encodeSuspend(bindingId, mask, responseRef, reasonRef), label: `suspend(${bindingId.slice(0, 10)}…, ${mask})` }) }],
+            output: async (confirmed) => ({ bindingId: bindingId, restrictions: mask, state: BindingStateName[(await k.asf.bindingOf(bindingId)).state] ?? "?", txHash: confirmed[0].txHash, jobId }),
+        };
+    },
+};
+export const guardian_resume = {
+    name: "guardian_resume",
+    title: "Resume the cell's binding",
+    description: "The guardian lifts the suspension of the cell's presented binding.",
+    action: "admin",
+    visibility: "operator",
+    principal: "cell",
+    signer: "guardian",
+    ercs: [8468],
+    input: z.object({ reason: z.string().min(1).max(500), jobId: zJobId }),
+    output: z.object({ bindingId: zBytes32, state: z.string(), txHash: z.string(), jobId: z.string() }),
+    async plan({ node }, input) {
+        const k = node.kernel;
+        const bindingId = node.config.identity.bindingId;
+        const gates = [];
+        if (!bindingId)
+            gates.push(refused("input", "the configuration names no binding (identity.bindingId)"));
+        else {
+            const b = await k.asf.bindingOf(bindingId);
+            const state = BindingStateName[b.state] ?? String(b.state);
+            if (state !== "Suspended")
+                gates.push(refused("policy", `binding ${bindingId.slice(0, 10)}… is ${state}, not Suspended`));
+            else
+                gates.push(ok("policy", `binding ${bindingId.slice(0, 10)}… Suspended`));
+        }
+        const jobId = input.jobId ?? derivedJobId("guardian-resume", { bindingId, reason: input.reason, at: Math.floor(Date.now() / 1000) });
+        return {
+            job: { id: jobId, kind: "admin", input: { bindingId, reason: input.reason } },
+            gates,
+            valueWei: 0n,
+            steps: [{ name: "resume", by: "guardian", route: "direct", build: () => ({ target: k.asf.bindingRegistryAddress, value: 0n, data: k.asf.encodeResume(bindingId, keccakJcs({ kind: "reason", summary: input.reason })), label: `resume(${bindingId.slice(0, 10)}…)` }) }],
+            output: async (confirmed) => ({ bindingId: bindingId, state: BindingStateName[(await k.asf.bindingOf(bindingId)).state] ?? "?", txHash: confirmed[0].txHash, jobId }),
+        };
+    },
+};
+export const binding_present = {
+    name: "binding_present",
+    title: "Present bindings",
+    description: "The owner re-points the account's presented bindings (presentBindings is onlyOwner); the account executes nothing until the presented set satisfies its requirement.",
+    action: "admin",
+    visibility: "operator",
+    principal: "cell",
+    signer: "owner",
+    ercs: [8468],
+    input: z.object({ bindingIds: z.array(zBytes32).min(1), jobId: zJobId }),
+    output: z.object({ bindingIds: z.array(zBytes32), verdict: z.string(), txHash: z.string(), jobId: z.string() }),
+    async plan({ node }, input) {
+        const cell = node.body;
+        const jobId = input.jobId ?? derivedJobId("binding-present", { bindingIds: input.bindingIds });
+        return {
+            job: { id: jobId, kind: "admin", input: { bindingIds: input.bindingIds } },
+            gates: [ok("policy", `${input.bindingIds.length} binding(s) to present`)],
+            valueWei: 0n,
+            steps: [{ name: "present", by: "owner", route: "direct", build: () => ({ target: cell.address, value: 0n, data: cell.iface.encodeFunctionData("presentBindings", [input.bindingIds]), label: "presentBindings" }) }],
+            output: async (confirmed) => {
+                node.config.identity.bindingId = input.bindingIds[0];
+                node.saveConfig();
+                return { bindingIds: input.bindingIds, verdict: (await cell.status()).verdictName, txHash: confirmed[0].txHash, jobId };
+            },
+        };
+    },
+};
+export const identity_transfer = {
+    name: "identity_transfer",
+    title: "Transfer the ERC-8004 identity",
+    description: "The owner moves the cell's ERC-8004 agent to another account through the cell's `execute` (an asset leaves the cell: the account refuses this to the operator). The anchor turns STALE until the successor binds; `foga cell migrate` does the whole move.",
+    action: "admin",
+    visibility: "operator",
+    principal: "cell",
+    signer: "owner",
+    ercs: [8004, 8434],
+    input: z.object({ to: zAddress, jobId: zJobId }),
+    output: z.object({ agentId: zUint, from: zAddress, to: zAddress, txHash: z.string(), jobId: z.string() }),
+    async plan({ node }, input) {
+        const k = node.kernel;
+        const cell = node.body;
+        const agentId = node.config.identity.agentId;
+        const gates = [];
+        if (!agentId)
+            gates.push(refused("input", "the configuration names no agentId"));
+        else {
+            const owner = await k.identity.ownerOf(BigInt(agentId));
+            if (getAddress(owner) !== getAddress(cell.address))
+                gates.push(refused("policy", `agent ${agentId} is held by ${owner}, not by the cell`));
+            else
+                gates.push(ok("policy", `agent ${agentId} held by the cell; moving to ${input.to}`));
+        }
+        const jobId = input.jobId ?? derivedJobId("identity-transfer", { agentId, to: input.to });
+        return {
+            job: { id: jobId, kind: "admin", input: { agentId, to: input.to } },
+            gates,
+            valueWei: 0n,
+            steps: [{ name: "transfer", by: "owner", route: "execute", build: () => ({ target: k.identity.address, value: 0n, data: k.identity.encodeTransfer(cell.address, input.to, BigInt(agentId)), label: `transferFrom(cell, ${input.to}, ${agentId})` }) }],
+            output: (confirmed) => ({ agentId: agentId, from: getAddress(cell.address), to: getAddress(input.to), txHash: confirmed[0].txHash, jobId }),
+        };
+    },
+};
+export const ADMIN_CAPABILITIES = [operator_rotate, guardian_suspend, guardian_resume, binding_present, identity_transfer];