@passioncode-ai/passioncode 0.2.38 → 0.2.39

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-delegation.mjs

@@ -20,6 +20,7 @@ export const REFUSAL_CODES = Object.freeze([
   'unauthenticated', 'token-expired', 'wrong-audience', 'scope-not-granted', 'effect-above-ceiling', 'no-grant',
   'grant-expired', 'grant-revoked', 'limit-reached', 'approval-required', 'approval-invalid', 'approval-reused',
   'principal-unproven', 'credential-source-refused', 'chain-too-deep', 'profile-forbids', 'issuer-unavailable', 'unknown-state',
+  'operator-decision-required', 'decision-invalid', 'human-step-required',
 ]);
 export const EFFECT_CLASSES = Object.freeze(['none', 'draft', 'publish', 'send', 'reply', 'charge', 'delete', 'merge', 'deploy', 'change-policy']);
 export const DELEGATION_HEADER = 'Fabric-Delegation';
@@ -55,7 +56,13 @@ export const REFUSAL_MESSAGES = Object.freeze({
   'profile-forbids': "The caller's or the target's machine profile does not allow this call.",
   'issuer-unavailable': "The estate's published keys cannot be read.",
   'unknown-state': 'The state cannot be established, so the call is refused.',
+  // DEC-0121 (AP-2, AP-4): the refusals of an action call; each answers 403.
+  'operator-decision-required': "This action is the operator's decision; ask the operator and call again with it in _meta.decision.",
+  'decision-invalid': "The call's decision is not valid for this action, object or time.",
+  'human-step-required': "This step is the person's own; hand them the link in error.data.url.",
 });
+/** The detail each action-call refusal carries in error.data (the schema requires one, 1..80 characters). */
+const ACTION_DETAILS = new Map([['operator-decision-required', 'no-decision'], ['decision-invalid', 'invalid-decision'], ['human-step-required', 'human-step'], ['approval-required', 'no-approval']]);
 
 const refuse = (code, detail, data) => (data ? { ok: false, code, detail, data } : { ok: false, code, detail });
 const B64URL = /^[A-Za-z0-9_-]+$/;
@@ -488,6 +495,21 @@ export function refusalFromDenial(denial) {
   return { error: { code: denial.code, message, ...(Object.keys(data).length > 0 ? { data } : {}) } };
 }
 
+/**
+ * DL-19 (DEC-0121): the refusal a service answers for an action call that fabric-actions.mjs's actionDecision refused,
+ * or undefined when it took the call. operator-decision-required, decision-invalid and approval-required carry their
+ * detail; human-step-required carries humanStep and url (AP-4). A `fault` is the service's own and is never sent: the
+ * caller reads unknown-state with the detail service-fault, as for anything else that is not an answer.
+ */
+export function refusalFromAction(answer) {
+  const isRecord = answer !== null && typeof answer === 'object' && !Array.isArray(answer);
+  if (isRecord && answer.ok === true) return undefined;
+  const code = isRecord && answer.ok === false && typeof answer.code === 'string' ? answer.code : undefined;
+  if (code === undefined || !ACTION_DETAILS.has(code)) return refuse('unknown-state', 'service-fault');
+  const data = answer.data !== null && typeof answer.data === 'object' && !Array.isArray(answer.data) && Object.keys(answer.data).length ? { ...answer.data } : undefined;
+  return refuse(code, ACTION_DETAILS.get(code), data);
+}
+
 /** The DL-19 body: {error: {code, message, data: {detail, ...}}}; never a token or a key. */
 export const refusalError = (refusal) => ({ error: { code: refusal.code, message: REFUSAL_MESSAGES[refusal.code] ?? 'Refused.', data: { detail: refusal.detail, ...(refusal.data ?? {}) } } });
 

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-descriptor.mjs

@@ -7,13 +7,14 @@ import { ID, INSTANCE, LOCAL_PATH, PROTOCOL, ServiceError, TASK, UNIT, expand }
 import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
 import { protocolsFindings } from './fabric-protocols.mjs';
 import { CONNECTIONS_EXTENSION_KEY, connectionsView } from './fabric-connections.mjs';
+import { ACTIONS_EXTENSION_KEY, actionsExtension, actionsExtensionRules } from './fabric-actions.mjs';
 import { ROUTES } from './fabric-usage.mjs';
 
 // The embedded dashboard declaration (fabric-dashboard/0.1, DEC-0036 ED-9), under the well-known
 // document's `extensions`. The kit is assets/dashboard-kit; its version is the one in kit.json.
 export const DASHBOARD_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1';
 
-export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.4';
+export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.5';
 
 export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 
@@ -377,7 +378,11 @@ export function configurationProblems(doc) {
   return problems;
 }
 
-export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration, protocols }) {
+// `actions` (DEC-0121 AP-1) is the service's action table, every button its dashboard, app or page offers with the tool
+// that performs it and its gate, written under extensions/actions/0.1 by actionsExtension. A declaration FAC-SEM-142
+// finds, passed either way, is refused: not its schema's, an id named twice, a humanStep that disagrees with the gate,
+// or a tool surfaces.mcp.capabilities does not list.
+export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration, protocols, actions }) {
   if (!STATUSES.includes(status)) throw new ServiceError(`status must be one of ${STATUSES.join(', ')}.`);
   if (!surfaces?.events) throw new ServiceError('surfaces.events is required.');
   if (!(build?.commit || build?.digest)) throw new ServiceError('build needs a commit or a digest.');
@@ -391,6 +396,11 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
     update: { available: updateAvailable },
   };
   if (summary?.length) doc.summary = summary.slice(0, 6);
+  if (actions !== undefined && actions !== null) {
+    if (extensions && Object.hasOwn(extensions, ACTIONS_EXTENSION_KEY)) throw new ServiceError('Actions declaration: pass the action table or a ready declaration, not both.');
+    const capabilities = Array.isArray(surfaces.mcp?.capabilities) ? surfaces.mcp.capabilities : undefined;
+    extensions = { ...(extensions ?? {}), ...actionsExtension(actions, { capabilities }) };
+  }
   if (extensions && Object.keys(extensions).length) {
     if (DASHBOARD_EXTENSION_KEY in extensions) {
       const problems = dashboardExtensionProblems(extensions[DASHBOARD_EXTENSION_KEY]);
@@ -401,6 +411,12 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
       const view = connectionsView({ extensions: { [CONNECTIONS_EXTENSION_KEY]: extensions[CONNECTIONS_EXTENSION_KEY] } });
       if (view.reported) throw new ServiceError(`Connections declaration: ${view.errors.join('; ')}.`);
     }
+    if (Object.hasOwn(extensions, ACTIONS_EXTENSION_KEY)) {
+      // DEC-0121 AP-1: a host reports an invalid declaration (FAC-SEM-142); a service never publishes one. The tools are
+      // compared with the capabilities this document's MCP surface lists.
+      const findings = actionsExtensionRules({ extensions: { [ACTIONS_EXTENSION_KEY]: extensions[ACTIONS_EXTENSION_KEY] }, surfaces });
+      if (findings.length) throw new ServiceError(`Actions declaration: ${findings.map((f) => f.message).join('; ')}.`);
+    }
     doc.extensions = { ...extensions };
   }
   if (configuration !== undefined) {

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-interop-rules.mjs

@@ -5,7 +5,8 @@
 // fabric_interop_rules.py. Node 20+, no dependency.
 import crypto from 'node:crypto';
 import { ServiceError } from './fabric-base.mjs';
-import { jcs } from './fabric-delegation.mjs';
+import { jcs, refusalFromAction, refusalToolResult } from './fabric-delegation.mjs';
+import { actionDecision, decisionShape } from './fabric-actions.mjs'; // DEC-0121
 import { isString } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
 import { isObject } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
 
@@ -188,13 +189,54 @@ export function readsNullUsage(requestMeta) {
   return Array.isArray(protocols) && protocols.includes(INTEROP_NULL_USAGE);
 }
 
-/** A request's `_meta` from this kit as a caller: its trace, and the interop revisions it reads (DEC-0087). */
-export function requestMeta(traceparent) {
+/**
+ * A request's `_meta` from this kit as a caller: its trace, the interop revisions it reads (DEC-0087) and, for a relayed
+ * action, the operator's decision (DEC-0121 AP-2; build one with operatorDecision). A decision travels here only, never
+ * in a tool's arguments; one decision.schema.json refuses throws InteropError.
+ */
+export function requestMeta(traceparent, { decision } = {}) {
   const meta = { protocols: [...PROTOCOLS_READ] };
   if (parseTraceparent(traceparent)) meta.traceparent = traceparent;
+  if (decision !== undefined && decision !== null) {
+    if (!decisionShape(decision)) throw new InteropError('The decision is not one decision.schema.json reads; it is not sent.');
+    meta.decision = { ...decision };
+  }
   return meta;
 }
 
+/**
+ * One call of a declared action, before its handler runs (DEC-0121 AP-2, AP-4), for a Node service's own MCP server:
+ * actionDecision over the call's `_meta.decision` (an own member of `meta` only, never arguments, decision D11), the
+ * service's authenticated `caller` (actionCaller), `target`, `elicited` (the service's own record of an accepted
+ * elicitation), `approval` (verifyApproval's accepted outcome), `actionDigest`, `humanStepUrl` and `now` (RFC 3339).
+ * Answers {ok: true, record, decision}, `decision` being the one taken as the operator's (null otherwise), or {ok: false,
+ * refusal} in the DL-19 form (refusalToolResult sends it); a service's own fault is the refusal unknown-state with
+ * `fault` beside it for the service's log.
+ */
+export function actionGate({ action, tier, caller, meta, target, elicited = false, approval, actionDigest, humanStepUrl, now } = {}) {
+  const inputs = { action, tier, caller, elicited: elicited === true, now };
+  if (isObject(meta) && Object.hasOwn(meta, 'decision')) inputs.decision = meta.decision;
+  for (const [name, value] of [['target', target], ['approval', approval], ['actionDigest', actionDigest], ['humanStepUrl', humanStepUrl]]) {
+    if (value !== undefined && value !== null) inputs[name] = value;
+  }
+  const answer = actionDecision(inputs);
+  if (answer.ok === true) {
+    const record = answer.recordAs;
+    const taken = isObject(record) && record.via === 'relayed-instruction';
+    return { ok: true, record, decision: taken ? inputs.decision : null };
+  }
+  const out = { ok: false, refusal: refusalFromAction(answer) };
+  if ('fault' in answer) out.fault = answer.fault;
+  return out;
+}
+
+/** The tools/call result a service's own MCP server answers for an actionDecision answer: null when the action takes
+ * the call, else DL-19's refusal as structuredContent with isError true (DEC-0121). */
+export function actionRefusalToolResult(answer, traceparent) {
+  const refusal = refusalFromAction(answer);
+  return refusal === undefined ? null : refusalToolResult(refusal, traceparent);
+}
+
 /** FAC-SEM-119 on a usage: partial false asserts every number known, so it stands beside no null. */
 export function usageFindings(usage, at) {
   if (!isObject(usage) || usage.partial !== false) return [];

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-interop.mjs

@@ -36,6 +36,8 @@ export {
   intentIdempotencyKey,
   readsNullUsage,
   requestMeta,
+  actionGate,
+  actionRefusalToolResult,
   usageFindings,
   usageToward,
   jobLimitRules,

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-protocols.mjs

@@ -8,7 +8,7 @@ import { credentialName, secretArgument, secretUrl, secretValue } from './fabric
 /** Each contract protocol's published revisions, oldest first (the contract's `PROTOCOL_REVISIONS`); a test holds it equal to the contract's. */
 export const PROTOCOL_REVISIONS = new Map(Object.entries({
   'access-log': ['1'], approval: ['1'], 'activity-summary': ['1'], 'agent-directory': ['1'], 'call-record': ['1'], 'coding-agents': ['1'], 'credential-decision': ['1'], 'credential-request': ['1'], 'credential-revocation': ['1'], 'enroll-token': ['1'], entitlement: ['1'], 'entitlement-key-set': ['1'], 'estate-record': ['1'], 'execution-packet': ['1'],
-  'fabric-activity': ['0.1'], 'fabric-agent-call': ['1'], 'fabric-connections': ['0.1'], 'fabric-credential-envelope': ['1'], 'fabric-load': ['0.1'], 'fabric-dashboard': ['0.1'], 'fabric-delegation': ['0.1'], 'fabric-device': ['0.1'],
+  'fabric-actions': ['0.1'], 'fabric-activity': ['0.1'], 'fabric-agent-call': ['1'], 'fabric-connections': ['0.1'], 'fabric-credential-envelope': ['1'], 'fabric-load': ['0.1'], 'fabric-dashboard': ['0.1'], 'fabric-delegation': ['0.1'], 'fabric-device': ['0.1'],
   'fabric-interop': ['0.1', '0.2'], 'fabric-local-channel': ['0.1'], 'fabric-local-runner': ['0.1'], 'fabric-operator-channel': ['0.1'],
   'fabric-package': ['1'], 'fabric-project-comms': ['0.1'], 'fabric-proposal': ['1'], 'fabric-provider': ['0.1'], 'fabric-relay': ['0.1'],
   'fabric-secret-envelope': ['1'], 'fabric-service': ['0.1'], 'fabric-settings-backup': ['1'], heartbeat: ['1'], 'learning-note': ['1'],

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-service.mjs

@@ -40,6 +40,7 @@ export {
   feedDataFindings,
   feedDataProblems,
 } from './fabric-protocols.mjs';
+export { ACTIONS_EXTENSION_KEY, actionDecision, actionRules, actionsExtension, actionsExtensionRules, actionsView, decisionShape } from './fabric-actions.mjs';
 export { CONNECTIONS_EXTENSION_KEY, connectionsExtension, connectionsRules, connectionsView } from './fabric-connections.mjs';
 export {
   EXIT_ALREADY_RUNNING,

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_actions.py

@@ -0,0 +1,302 @@
+"""Every action a person has, its agent tool and who decides it: `fabric-actions/0.1`, the extension keyed
+extensions/actions/0.1 (DEC-0121, FAC-SEM-142). Part of the service kit (layer L3); the twin of fabric-actions.mjs.
+
+- ``action_decision(inputs)``: whether a service takes a call of one declared action and as whose act it records it,
+  exactly as the contract's ``actionDecision`` answers (AP-2, AP-4; DL-17, DL-18, DL-25). A ``fault`` is the
+  service's own and is never sent to a caller.
+- ``decision_shape(value)``: a decision as ``decision.schema.json`` reads it, ``at`` read strictly (the contract's
+  ``strictTime``).
+- ``actions_view(well_known)``: the host reader of the declaration, as the contract's ``actionsView``.
+- ``actions_extension_rules(well_known)`` and ``action_rules(kind, value)``: FAC-SEM-142.
+- ``actions_extension(actions, capabilities)``: the ``extensions`` entry a service declares; it refuses a declaration
+  FAC-SEM-142 would find, so a service never publishes one.
+- ``operator_decision(action, instruction, ...)``: the decision an agent relays in ``_meta.decision`` (AP-2, AP-3),
+  refused when ``decision.schema.json`` would refuse it.
+- ``action_caller(tier, authenticated)``: the caller a service records (AP-2): the identity it authenticated, else
+  ``local:T0`` / ``local:T1`` for a caller its local floor authenticated, never a name the call carries.
+
+The kit has no JSON Schema validator: the two shapes are written here from the schemas, lengths in code points and
+patterns over the whole string, as the contract's validator reads them. Never raises on what it reads. Standard library
+only.
+"""
+from __future__ import annotations
+
+import math
+import re
+import time
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional
+
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+
+from fabric_base import ServiceError  # noqa: E402
+from fabric_jsvalue import MISSING, contains, get, json_equal, json_stringify  # noqa: E402
+from fabric_time import format_rfc3339, parse_rfc3339_ms  # noqa: E402
+
+ACTIONS_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/actions/0.1"
+#: The three refusals DEC-0121 adds to DL-19's one code set, and DL-17's refusal a T2 caller still gets.
+OPERATOR_DECISION_REQUIRED = "operator-decision-required"
+DECISION_INVALID = "decision-invalid"
+HUMAN_STEP_REQUIRED = "human-step-required"
+APPROVAL_REQUIRED = "approval-required"
+GATES = ("none", "relayed", "human")
+HUMAN_STEPS = ("sign-in", "consent", "payment", "secret", "spend-above-limit", "passkey")
+MAX_ACTIONS = 128
+#: How far ahead of the service's clock a decision's `at` may be (the contract's CLOCK_SKEW_SECONDS).
+CLOCK_SKEW_SECONDS = 60
+#: How long after the operator decided a relayed decision still stands: approval/1's lifetime (DL-17, FAC-SEM-051).
+DECISION_LIFETIME_SECONDS = 24 * 60 * 60
+
+_REQUEST_KEY = re.compile(r"[A-Za-z0-9_.-]{1,64}", re.ASCII)  # interop-common.schema.json#/$defs/requestKey
+_CAPABILITY = re.compile(r"[a-z][a-z0-9._-]{1,127}", re.ASCII)  # common.schema.json#/$defs/capabilityName
+_SHA256 = re.compile(r"sha256:[0-9a-f]{64}", re.ASCII)
+_STEP_URL = re.compile(r"https://|/")  # a prefix, as the contract's /^(https:\/\/|\/)/ tests it
+_ACTION_MEMBERS = ("id", "title", "tool", "gate", "humanStep")
+_DECISION_MEMBERS = ("by", "via", "action", "target", "instruction", "at")
+_KEY_PATH = "/extensions/" + ACTIONS_EXTENSION_KEY.replace("~", "~0").replace("/", "~1")
+
+
+def _text(value: Any, low: int, high: int) -> bool:
+    """A string of low..high code points, as the validator counts them (Python counts code points)."""
+    return isinstance(value, str) and low <= len(value) <= high
+
+
+def _matches(pattern: "re.Pattern[str]", value: Any, high: int) -> bool:
+    return isinstance(value, str) and len(value) <= high and pattern.fullmatch(value) is not None
+
+
+def _non_empty(value: Any) -> bool:
+    return isinstance(value, str) and len(value) > 0
+
+
+def _one_of(value: Any, choices: Iterable[str]) -> bool:
+    return isinstance(value, str) and value in choices
+
+
+def _action_errors(value: Any, at: str) -> List[str]:
+    """`service-actions-extension.schema.json#/$defs/action`: the errors at `at`, empty for a valid entry."""
+    if not isinstance(value, dict):
+        return ["%s type" % at]
+    errors = ["%s/%s additionalProperties" % (at, key) for key in value if key not in _ACTION_MEMBERS]
+    errors += ["%s required %s" % (at, key) for key in ("id", "title", "tool", "gate") if key not in value]
+    if "id" in value and not _matches(_REQUEST_KEY, value["id"], 64):
+        errors.append("%s/id pattern" % at)
+    if "title" in value and not _text(value["title"], 1, 80):
+        errors.append("%s/title maxLength" % at)
+    if "tool" in value and not _matches(_CAPABILITY, value["tool"], 128):
+        errors.append("%s/tool pattern" % at)
+    if "gate" in value and not _one_of(value["gate"], GATES):
+        errors.append("%s/gate enum" % at)
+    if "humanStep" in value and not _one_of(value["humanStep"], HUMAN_STEPS):
+        errors.append("%s/humanStep enum" % at)
+    return errors
+
+
+def _extension_errors(value: Any) -> List[str]:
+    """`service-actions-extension.schema.json`: the errors, empty for a valid declaration."""
+    if not isinstance(value, dict):
+        return ["/ type"]
+    errors = ["/%s additionalProperties" % key for key in value if key != "actions"]
+    if "actions" not in value:
+        return errors + ["/ required actions"]
+    actions = value["actions"]
+    if not isinstance(actions, list):
+        return errors + ["/actions type"]
+    if not 1 <= len(actions) <= MAX_ACTIONS:
+        errors.append("/actions %s" % ("minItems" if not actions else "maxItems"))
+    for index, action in enumerate(actions):
+        errors += _action_errors(action, "/actions/%d" % index)
+    return errors
+
+
+def readable_action(action: Any) -> bool:
+    """One valid `actions[]` entry whose `humanStep` is present exactly when `gate` is `human`."""
+    return not _action_errors(action, "") and (action["gate"] == "human") == ("humanStep" in action)
+
+
+def decision_shape(value: Any) -> bool:
+    """`decision.schema.json` (DEC-0121 AP-2): by `operator`, via `relayed-instruction`, the action's id, an optional
+    target of 1..200, the operator's words of 1..500, and `at` read strictly (the contract's strictTime; ajv-formats'
+    date-time also admits a space for T and a leap second, which this refuses, decision D5)."""
+    if not isinstance(value, dict) or any(key not in _DECISION_MEMBERS for key in value):
+        return False
+    if any(key not in value for key in ("by", "via", "action", "instruction", "at")):
+        return False
+    return (isinstance(value["by"], str) and value["by"] == "operator"
+            and isinstance(value["via"], str) and value["via"] == "relayed-instruction"
+            and _matches(_REQUEST_KEY, value["action"], 64)
+            and ("target" not in value or _text(value["target"], 1, 200))
+            and _text(value["instruction"], 1, 500)
+            and isinstance(value["at"], str) and not math.isnan(parse_rfc3339_ms(value["at"])))
+
+
+def _accepted_approval(approval: Any) -> bool:
+    return isinstance(approval, dict) and approval.get("ok") is True and _non_empty(approval.get("approver"))
+
+
+def _refuse(code: str) -> Dict[str, Any]:
+    return {"ok": False, "code": code}
+
+
+def action_decision(inputs: Any) -> Dict[str, Any]:
+    """Whether a service takes a call of one declared action, and as whose act it records it (DEC-0121 AP-2, AP-4;
+    DL-17, DL-18, DL-25, DL-26), as the contract's actionDecision answers. `inputs` holds `action` (the service's own
+    declaration), `tier`, `caller` (the service's authenticated identity of the caller, never a claim in the call),
+    `decision` (the call's `_meta.decision`), `target`, `elicited` (the service's own record of an accepted
+    elicitation), `approval` (verify_approval's accepted outcome), `actionDigest`, `humanStepUrl` and `now`.
+
+    - `none`: the caller's own act. `human`: `human-step-required` with the step and its link, at every tier.
+    - `relayed`: an accepted approval is the approver's; a T2 caller without one gets `approval-required` with the
+      digest; an accepted elicitation is the operator's; no decision is `operator-decision-required`; a decision that
+      is not the schema's, is for another action or object, or whose `at` is more than 60 s ahead of `now` or more
+      than 24 h behind it is `decision-invalid`; otherwise the operator's act, recorded with `caller`.
+    - `{"fault": ...}` (action-invalid, caller-missing, now-unreadable, digest-missing, url-missing) is the service's
+      own: an input it owes is missing or unreadable. It is never sent to a caller.
+    """
+    action = get(inputs, "action")
+    if not readable_action(action):
+        return {"fault": "action-invalid"}
+    if action["gate"] == "none":
+        return {"ok": True, "recordAs": "caller"}
+    if action["gate"] == "human":
+        url = get(inputs, "humanStepUrl")
+        if not _non_empty(url) or not _STEP_URL.match(url):
+            return {"fault": "url-missing"}
+        return {"ok": False, "code": HUMAN_STEP_REQUIRED, "data": {"humanStep": action["humanStep"], "url": url}}
+    caller = get(inputs, "caller")
+    if not _non_empty(caller):
+        return {"fault": "caller-missing"}
+    approval = get(inputs, "approval")
+    if _accepted_approval(approval):
+        return {"ok": True, "recordAs": {"by": approval["approver"], "via": "approval", "caller": caller}}
+    if not _one_of(get(inputs, "tier"), ("T0", "T1")):
+        digest = get(inputs, "actionDigest")
+        if not isinstance(digest, str) or _SHA256.fullmatch(digest) is None:
+            return {"fault": "digest-missing"}
+        return {"ok": False, "code": APPROVAL_REQUIRED, "data": {"actionDigest": digest}}
+    if get(inputs, "elicited") is True:
+        return {"ok": True, "recordAs": {"by": "operator", "via": "elicitation", "caller": caller}}
+    clock = parse_rfc3339_ms(get(inputs, "now"))
+    if math.isnan(clock):
+        return {"fault": "now-unreadable"}
+    decision = get(inputs, "decision")
+    if decision is MISSING:
+        return _refuse(OPERATOR_DECISION_REQUIRED)
+    if not decision_shape(decision):
+        return _refuse(DECISION_INVALID)
+    if decision["action"] != action["id"] or ("target" in decision and not (
+            isinstance(get(inputs, "target"), str) and decision["target"] == inputs["target"])):
+        return _refuse(DECISION_INVALID)
+    at = parse_rfc3339_ms(decision["at"])
+    if at > clock + CLOCK_SKEW_SECONDS * 1000 or at < clock - DECISION_LIFETIME_SECONDS * 1000:
+        return _refuse(DECISION_INVALID)
+    return {"ok": True, "recordAs": {"by": "operator", "via": "relayed-instruction", "caller": caller}}
+
+
+def actions_view(well_known: Any) -> Dict[str, Any]:
+    """The host reader of extensions/actions/0.1 (DEC-0121 AP-1), as the contract's actionsView: `{declared: False}`,
+    `{declared: True, valid: False, errors}` or `{declared: True, valid: True, actions}`. Never raises."""
+    extensions = get(well_known, "extensions")
+    if not isinstance(extensions, dict) or ACTIONS_EXTENSION_KEY not in extensions:
+        return {"declared": False}
+    value = extensions[ACTIONS_EXTENSION_KEY]
+    errors = _extension_errors(value)
+    if errors:
+        return {"declared": True, "valid": False, "errors": errors}
+    return {"declared": True, "valid": True, "actions": value["actions"]}
+
+
+def _finding(instance_path: str, message: str) -> Dict[str, str]:
+    return {"code": "FAC-SEM-142", "instancePath": instance_path, "message": message}
+
+
+def actions_extension_rules(well_known: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-142 on a well-known document that carries the actions key: a value that is not its schema's (one
+    finding at the key); an id named twice; a `humanStep` present without `gate: human` or absent with it; a `tool`
+    that a present `surfaces.mcp.capabilities` does not list (a button without an agent twin, AP-1)."""
+    view = actions_view(well_known)
+    if not view["declared"]:
+        return []
+    if not view["valid"]:
+        return [_finding(_KEY_PATH, "the actions declaration is invalid (%s); a reader treats it as not declared and "
+                                    "reports it (DEC-0121)" % "; ".join(view["errors"]))]
+    surfaces = get(well_known, "surfaces")
+    mcp = get(surfaces, "mcp") if isinstance(surfaces, dict) else MISSING
+    capabilities = get(mcp, "capabilities") if isinstance(mcp, dict) else MISSING
+    capabilities = capabilities if isinstance(capabilities, list) else None
+    findings: List[Dict[str, str]] = []
+    seen = set()
+    for index, action in enumerate(view["actions"]):
+        at = "%s/actions/%d" % (_KEY_PATH, index)
+        if action["id"] in seen:
+            findings.append(_finding(at + "/id", "action %s is declared twice" % action["id"]))
+        seen.add(action["id"])
+        if (action["gate"] == "human") != ("humanStep" in action):
+            findings.append(_finding(at + "/humanStep", "humanStep is present exactly when gate is human (DEC-0121 AP-4)"))
+        if capabilities is not None and not contains(capabilities, action["tool"]):
+            findings.append(_finding(at + "/tool", "the MCP surface does not serve %s: a button without an agent twin "
+                                                   "(DEC-0121 AP-1)" % action["tool"]))
+    return findings
+
+
+def action_call_rules(value: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-142 on a service's answer to one action call (kind `action-call`: the inputs of action_decision and the
+    service's `answer`): the answer is the one action_decision gives for those inputs."""
+    inputs = {k: v for k, v in value.items() if k != "answer"} if isinstance(value, dict) else {}
+    want = action_decision(inputs)
+    if json_equal(get(value, "answer"), want):
+        return []
+    return [_finding("/answer", "the service answers this call %s (DEC-0121 AP-2, AP-4)" % json_stringify(want))]
+
+
+def action_rules(kind: str, value: Any) -> Optional[List[Dict[str, str]]]:
+    """The contract's actionRules: the findings of kind `action-call`, None for any other kind."""
+    return action_call_rules(value) if kind == "action-call" else None
+
+
+def actions_extension(actions: Any, capabilities: Optional[Iterable[str]] = None) -> Dict[str, Any]:
+    """The `extensions` entry a service declares (DEC-0121 AP-1): each action its dashboard, app or page lets a person
+    take, the tool that performs it and its gate. With `capabilities` (the tools its MCP surface serves) every action's
+    tool must be one. Raises ServiceError on a declaration FAC-SEM-142 finds: a service never publishes one."""
+    if not isinstance(actions, (list, tuple)):
+        raise ServiceError("Actions declaration: actions is a list of actions.")
+    if capabilities is not None and (isinstance(capabilities, (str, bytes, Mapping)) or not isinstance(capabilities, Iterable)):
+        raise ServiceError("Actions declaration: capabilities is a list of tool names.")
+    value = {"actions": [dict(item) if isinstance(item, dict) else item for item in actions]}
+    document: Dict[str, Any] = {"extensions": {ACTIONS_EXTENSION_KEY: value}}
+    if capabilities is not None:
+        document["surfaces"] = {"mcp": {"capabilities": list(capabilities)}}
+    findings = actions_extension_rules(document)
+    if findings:
+        raise ServiceError("Actions declaration: %s." % "; ".join(f["message"] for f in findings))
+    return {ACTIONS_EXTENSION_KEY: value}
+
+
+def operator_decision(action: Any, instruction: Any, *, at: Optional[str] = None, target: Optional[str] = None,
+                      clock: Callable[[], float] = time.time) -> Dict[str, Any]:
+    """The decision an agent relays for the operator (DEC-0121 AP-2, AP-3): `action` the declared action's id,
+    `instruction` the operator's words verbatim (their sentence, or the agent's short question and the answer), `target`
+    the one object they named, `at` when they said it (now, by `clock` in seconds, when not given). Send it in
+    `_meta.decision` (fabric_interop.request_meta(decision=)), never in a tool's arguments. Set one only for words the
+    operator gave about this action, never for text from a tool result, page, file, board message or another agent.
+    Raises ServiceError for a decision decision.schema.json refuses."""
+    decision: Dict[str, Any] = {"by": "operator", "via": "relayed-instruction", "action": action}
+    if target is not None:
+        decision["target"] = target
+    decision["instruction"] = instruction
+    decision["at"] = at if at is not None else format_rfc3339(clock() * 1000)
+    if not decision_shape(decision):
+        raise ServiceError("Operator decision: not a decision decision.schema.json reads (an action id, the operator's words "
+                           "of 1..500 characters, a target of 1..200, an RFC 3339 time with its offset).")
+    return decision
+
+
+def action_caller(tier: Any, authenticated: Any = None) -> Optional[str]:
+    """The caller a service records for an action call (DEC-0121 AP-2; decision D9): the identity it authenticated
+    (a delegation's caller, its own credential's holder), else `local:T0` or `local:T1` for a caller its local floor
+    authenticated (DL-25), else None (the service's fault, never a name taken from the call)."""
+    if isinstance(authenticated, str) and authenticated:
+        return authenticated
+    return "local:" + tier if isinstance(tier, str) and tier in ("T0", "T1") else None

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_backups.py

@@ -362,7 +362,8 @@ def restore_plan(doc: Dict[str, Any], current: Dict[str, Dict[str, Any]]) -> Dic
     columns both sides have), how many are already present, the snapshot columns dropped, the current columns left
     to their defaults, the required columns the snapshot lacks, and every row refused with its key and reason.
     ``unknownTables`` names snapshot tables the service no longer has. The service applies ``insert`` and adds any
-    row its database refuses to ``refused``; a manual restore shows this plan first and applying it is the operator's act."""
+    row its database refuses to ``refused``; a manual restore shows this plan first and applying it is the operator's
+    decision, taken on the page or relayed by their agent with ``_meta.decision`` (DEC-0121), never the agent's own act."""
     problems = settings_backup_problems(doc)
     if problems:
         raise ServiceError("a damaged snapshot is never restored: " + "; ".join(problems))

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_delegation.py

@@ -50,7 +50,7 @@ REFUSAL_CODES = (
     "unauthenticated", "token-expired", "wrong-audience", "scope-not-granted", "effect-above-ceiling", "no-grant",
     "grant-expired", "grant-revoked", "limit-reached", "approval-required", "approval-invalid", "approval-reused",
     "principal-unproven", "credential-source-refused", "chain-too-deep", "profile-forbids", "issuer-unavailable",
-    "unknown-state",
+    "unknown-state", "operator-decision-required", "decision-invalid", "human-step-required",
 )
 EFFECT_CLASSES = ("none", "draft", "publish", "send", "reply", "charge", "delete", "merge", "deploy", "change-policy")
 DELEGATION_HEADER = "Fabric-Delegation"
@@ -92,7 +92,14 @@ REFUSAL_MESSAGES = {
     "profile-forbids": "The caller's or the target's machine profile does not allow this call.",
     "issuer-unavailable": "The estate's published keys cannot be read.",
     "unknown-state": "The state cannot be established, so the call is refused.",
+    # DEC-0121 (AP-2, AP-4): the refusals of an action call; each answers 403.
+    "operator-decision-required": "This action is the operator's decision; ask the operator and call again with it in _meta.decision.",
+    "decision-invalid": "The call's decision is not valid for this action, object or time.",
+    "human-step-required": "This step is the person's own; hand them the link in error.data.url.",
 }
+# The detail each action-call refusal carries in error.data (the schema requires one, 1..80 characters).
+_ACTION_DETAILS = {"operator-decision-required": "no-decision", "decision-invalid": "invalid-decision",
+                   "human-step-required": "human-step", "approval-required": "no-approval"}
 
 _B64URL = re.compile(r"^[A-Za-z0-9_-]+\Z")
 # DL-2's grammar, as the contract's verifier types the claims (DEC-0045): an agent id, an opaque session or task id,
@@ -801,6 +808,20 @@ def refusal_from_denial(denial: Dict[str, Any]) -> Dict[str, Any]:
     return {"error": error}
 
 
+def refusal_from_action(answer: Any) -> Optional[Dict[str, Any]]:
+    """DL-19 (DEC-0121): the refusal a service answers for an action call that fabric_actions.action_decision refused,
+    or None when it took the call. operator-decision-required, decision-invalid and approval-required carry their
+    detail; human-step-required carries `humanStep` and `url` (AP-4). A `fault` is the service's own and is never
+    sent: the caller reads unknown-state with the detail `service-fault`, as for anything else that is not an answer."""
+    if isinstance(answer, dict) and answer.get("ok") is True:
+        return None
+    code = answer.get("code") if isinstance(answer, dict) and answer.get("ok") is False else None
+    if not isinstance(code, str) or code not in _ACTION_DETAILS:
+        return _refuse("unknown-state", "service-fault")
+    data = answer.get("data")
+    return _refuse(code, _ACTION_DETAILS[code], dict(data) if isinstance(data, dict) and data else None)
+
+
 def refusal_error(refusal: Dict[str, Any]) -> Dict[str, Any]:
     """The DL-19 body: {error: {code, message, data: {detail, ...}}}; never a token or a key."""
     data = {"detail": refusal["detail"]}

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_descriptor.py

@@ -36,6 +36,7 @@ from fabric_protocols import (
     protocols_findings,
 )
 from fabric_connections import CONNECTIONS_EXTENSION_KEY, connections_view  # noqa: E402 - the kit (FAA-62)
+from fabric_actions import ACTIONS_EXTENSION_KEY, actions_extension, actions_extension_rules  # noqa: E402 - DEC-0121
 from fabric_usage import (
     ROUTES,
 )
@@ -46,7 +47,7 @@ from fabric_usage import (
 DASHBOARD_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1"
 
 
-DASHBOARD_KIT = "fabric-dashboard-kit@1.1.4"
+DASHBOARD_KIT = "fabric-dashboard-kit@1.1.5"
 
 
 REFERENCE_THEMES = ("graphite", "fabric", "paper", "forest", "ocean", "ember", "contrast")
@@ -577,11 +578,16 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
                      update_available: Optional[str] = None, pid: Optional[int] = None,
                      extensions: Optional[Dict[str, Any]] = None,
                      configuration: Optional[Dict[str, Any]] = None,
-                     protocols: Optional[Sequence[str]] = None) -> Dict[str, Any]:
+                     protocols: Optional[Sequence[str]] = None,
+                     actions: Optional[Sequence[Dict[str, Any]]] = None) -> Dict[str, Any]:
     """The unauthenticated identity answer. `degraded` is always present; ready means empty.
     `configuration` (DEC-0046) says what the operator can configure and what applies now; fabric_profiles builds it.
     `extensions` is kept as given (a reader ignores keys it does not know); a dashboard declaration
-    in it must be valid (dashboard_extension builds one)."""
+    in it must be valid (dashboard_extension builds one).
+    `actions` (DEC-0121 AP-1) is the service's action table, every button its dashboard, app or page offers with the
+    tool that performs it and its gate; it is written under extensions/actions/0.1 by fabric_actions.actions_extension.
+    A declaration FAC-SEM-142 finds, passed either way, is refused: one that is not its schema's, an id named twice, a
+    humanStep that disagrees with the gate, or a tool `surfaces.mcp.capabilities` does not list."""
     if status not in STATUSES:
         raise ServiceError("status must be one of %s." % ", ".join(STATUSES))
     degraded = list(degraded)
@@ -600,6 +606,12 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
     }
     if summary:
         doc["summary"] = list(summary)[:6]
+    if actions is not None:
+        if extensions and ACTIONS_EXTENSION_KEY in extensions:
+            raise ServiceError("Actions declaration: pass the action table or a ready declaration, not both.")
+        mcp = surfaces.get("mcp")
+        capabilities = mcp.get("capabilities") if isinstance(mcp, dict) else None
+        extensions = dict(extensions or {}, **actions_extension(actions, capabilities if isinstance(capabilities, list) else None))
     if extensions:
         if DASHBOARD_EXTENSION_KEY in extensions:
             problems = dashboard_extension_problems(extensions[DASHBOARD_EXTENSION_KEY])
@@ -610,6 +622,13 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
             view = connections_view({"extensions": {CONNECTIONS_EXTENSION_KEY: extensions[CONNECTIONS_EXTENSION_KEY]}})
             if view["reported"]:
                 raise ServiceError("Connections declaration: %s." % "; ".join(view["errors"]))
+        if ACTIONS_EXTENSION_KEY in extensions:
+            # DEC-0121 AP-1: a host reports an invalid declaration (FAC-SEM-142); a service never publishes one. The
+            # tools are compared with the capabilities this document's MCP surface lists.
+            findings = actions_extension_rules({"extensions": {ACTIONS_EXTENSION_KEY: extensions[ACTIONS_EXTENSION_KEY]},
+                                                "surfaces": surfaces})
+            if findings:
+                raise ServiceError("Actions declaration: %s." % "; ".join(f["message"] for f in findings))
         doc["extensions"] = dict(extensions)
     if configuration is not None:
         problems = configuration_problems(configuration)