apcore-a2a 0.4.4 → 0.6.0

package/README.md

@@ -40,7 +40,7 @@ Built on [`@a2a-js/sdk`](https://www.npmjs.com/package/@a2a-js/sdk) and [Express
 ## Requirements
 
 - Node.js >= 18.0.0
-- `apcore-js` >= 0.22.0
+- `apcore-js` >= 0.28.0
 
 ---
 

package/dist/adapters/agent-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-card.d.ts","sourceRoot":"","sources":["../../src/adapters/agent-card.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEvE,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,MAAM,EAAE,CAAC;IACjB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;CACxD;AAqBD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAA0B;gBAEhC,WAAW,EAAE,WAAW;IAIpC,KAAK,CACH,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,YAAY,EAAE,iBAAiB,CAAC;QAChC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC3C,GACA,SAAS;IAyCZ,gBAAgB,CACd,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,YAAY,EAAE,iBAAiB,CAAC;QAChC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC3C,GACA,SAAS;IAKZ,aAAa,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS;IAI7C,eAAe,IAAI,IAAI;IAIvB,OAAO,CAAC,WAAW;CAapB"}
+{"version":3,"file":"agent-card.d.ts","sourceRoot":"","sources":["../../src/adapters/agent-card.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEvE,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,MAAM,EAAE,CAAC;IACjB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;CACxD;AAqBD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAA0B;gBAEhC,WAAW,EAAE,WAAW;IAIpC,KAAK,CACH,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,YAAY,EAAE,iBAAiB,CAAC;QAChC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC3C,GACA,SAAS;IAwDZ,gBAAgB,CACd,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,YAAY,EAAE,iBAAiB,CAAC;QAChC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC3C,GACA,SAAS;IAKZ,aAAa,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS;IAI7C,eAAe,IAAI,IAAI;IAIvB,OAAO,CAAC,WAAW;CAapB"}

package/dist/adapters/agent-card.js

@@ -39,6 +39,21 @@ export class AgentCardBuilder {
                     tenant: "",
                     protocolVersion: "1.0",
                 },
+                // A2A 0.3 mirror of the same binding. Not decoration: a2a-js runs
+                // `validateVersion(requestedVersion, card, "JSONRPC")` before dispatch
+                // on both the v1.0 and the v0.3 compat path, and a request with no
+                // `A2A-Version` header is a 0.3 request per spec section 3.6.2 -- so
+                // without this entry every header-less request is refused -32009,
+                // including everything this package's own Explorer and A2AClient send.
+                // apcore-a2a-python needs no equivalent because a2a-python's
+                // `enable_v0_3_compat` does not consult the card; this entry is what
+                // buys apcore-a2a-typescript the same 0.3 acceptance.
+                {
+                    url: opts.url,
+                    protocolBinding: "JSONRPC",
+                    tenant: "",
+                    protocolVersion: "0.3",
+                },
             ],
             provider: undefined,
             skills,

package/dist/adapters/agent-card.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-card.js","sourceRoot":"","sources":["../../src/adapters/agent-card.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-card.js","sourceRoot":"","sources":["../../src/adapters/agent-card.ts"],"names":[],"mappings":"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"}

package/dist/adapters/card-visibility.d.ts

@@ -0,0 +1,148 @@
+import type { AgentCard } from "@a2a-js/sdk";
+import { type Identity } from "apcore-js";
+import type { ModuleDescriptor } from "./skill-mapper.js";
+/**
+ * Agent Card skill visibility — who gets to see which skills.
+ *
+ * apcore's ACL is the authority on who may invoke what, and the discovery
+ * surface reflects that authority rather than ignoring it. Two surfaces, two
+ * answers:
+ *
+ * - the **public** card (srs FR-AGC-003) answers "what may *anyone* call": every
+ *   registered skill, minus apcore's reserved `system.*` management namespace,
+ *   minus those the ACL denies to the anonymous principal, minus those gated
+ *   behind a human. It resolves exactly one identity, so it is computed once when
+ *   the card is built. A per-caller filter here
+ *   would be strictly more accurate and unaffordable: `/.well-known/` is
+ *   auth-exempt by design, so every anonymous request would drive
+ *   `skills.length` calls into the consumer's ACL audit sink, each recording a
+ *   `deny` decision indistinguishable from a real enforcement event, at whatever
+ *   rate the client chooses.
+ *
+ * - the **extended** card (srs FR-AGC-004) answers "what may *you* call": the
+ *   ACL resolved against the authenticated identity, with `requires_approval`
+ *   skills restored — an approval gate is a prompt the caller can satisfy, not a
+ *   refusal. Affordable precisely because that endpoint requires credentials.
+ *
+ * Only the `system.*` subtraction is unconditional. Every other one is
+ * governance-shaped, and with no ACL configured they collapse: the ACL predicates
+ * are empty and the `requires_approval` annotation covers only
+ * `system.control.*`, leaving the six read modules to publish the deployment's
+ * module inventory, health and usage to any anonymous caller. `ACL.discover()`
+ * yields nothing for a missing root by design, so "no ACL at all" is the default
+ * rather than an edge case — which is why the rule that has to hold there keys on
+ * apcore's namespace and not on a governance verdict (srs FR-AGC-003 criteria 12
+ * and 13).
+ *
+ * Authorization and approval are two independent results, not one (apcore
+ * PROTOCOL_SPEC §6.1.6), and this module reads them apart. `ACL.check` folds
+ * them into a boolean that **fails closed** on an approval requirement —
+ * correct for a caller about to execute, wrong for a discovery surface, where it
+ * would delete a skill from the extended card for the one reason FR-AGC-004 says
+ * to keep it. `ACL.checkAccess` carries both axes, so `access` decides
+ * visibility and `approvalRequired` decides only whether the public card is the
+ * right surface.
+ *
+ * Before this module, this binding filtered nothing at all: `buildSkills`
+ * iterated `registry.list()` and never consulted the ACL, so a module the ACL
+ * denied to everyone was still advertised — by id, name, description and full
+ * input schema — to any anonymous caller.
+ *
+ * **Internal module.** The `export` keywords below are module visibility, not a
+ * public contract: `package.json` declares only `"."` in `exports`, so a
+ * consumer cannot deep-import this file at all, and nothing here appears in
+ * `docs/features/public-api.md`. The surface is expected to move —
+ * `allowedSkillIds` already changed meaning once (it now reports the
+ * authorization axis alone, where it used to fold in the approval gate). Depend
+ * on `serve` / `A2AServerFactory` instead.
+ */
+/**
+ * apcore's reserved namespace for the runtime's own management modules (apcore
+ * PROTOCOL_SPEC §6.7) — `system.health.*`, `system.usage.*`, `system.manifest.*`
+ * and, under the second opt-in, `system.control.*`. apcore identifies the
+ * surface by this prefix itself, in `Executor.governanceState()`, so matching on
+ * it conveys apcore's own boundary rather than inventing one.
+ */
+export declare const SYSTEM_NAMESPACE = "system.";
+/** Whether `skillId` is one of apcore's management modules. */
+export declare function isSystemSkill(skillId: string): boolean;
+/** The two axes of one ACL decision (apcore PROTOCOL_SPEC §6.8.1). */
+export interface AccessDecisionLike {
+    readonly access: "allow" | "deny";
+    readonly approvalRequired: boolean;
+}
+/** The minimum surface this module reads off an apcore ACL. */
+export interface AclLike {
+    check(callerId: string | null, targetId: string, context?: unknown): boolean;
+    checkAccess?(callerId: string | null, targetId: string, context?: unknown): AccessDecisionLike;
+}
+/** The minimum surface this module reads off an apcore Registry. */
+export interface RegistryLike {
+    list(): string[];
+    getDefinition(moduleId: string): ModuleDescriptor | null | undefined;
+}
+/**
+ * The apcore ACL backing `executor`, if one is configured.
+ *
+ * apcore-js exposes `setAcl` but no getter, so this reads the public property
+ * when one appears upstream and falls back to the private field. `null` means
+ * "no ACL configured", which is the common case and leaves every card
+ * unfiltered.
+ */
+export declare function executorAcl(executor: unknown): AclLike | null;
+/**
+ * The skills the ACL permits `identity` to invoke, each mapped to whether
+ * invoking it needs a human first.
+ *
+ * With no ACL configured every id is permitted and none is gated, which is what
+ * makes this free for the common single-tenant deployment.
+ *
+ * The ACL is consulted with **no arguments projection**, because a card is
+ * discovery and there is no call site yet. An `arguments` condition (§6.1.7) is
+ * therefore unevaluable, so a rule carrying one neither denies nor grants — but
+ * an `allow` rule's `approval: required` stays *pending* and composes with
+ * whatever grants (§6.1.1 rule 5). A skill gated only for some argument shapes
+ * thus reports `true` here: at discovery time "this may need approval" is the
+ * honest answer, and it is the one that keeps such a skill off the public card.
+ *
+ * `callerId` is left `null` deliberately. apcore defines it as the *calling
+ * module* in a nested call chain, managed by `Context.child`; a top-level
+ * inbound request has none, and the ACL maps `null` to `@external`. That is
+ * apcore's contract, not a gap — `callers: ["@external"]` is how an operator
+ * denies external access, and it has to keep matching an authenticated request
+ * or the rule silently stops covering the traffic it was written for. The
+ * authenticated principal travels in the context instead, where the
+ * `identityTypes` / `roles` conditions see it.
+ */
+export declare function skillAccess(executor: unknown, skillIds: readonly string[], identity: Identity | null): Map<string, boolean>;
+/**
+ * The subset of `skillIds` the ACL authorizes `identity` to invoke.
+ *
+ * The authorization axis alone: a skill the ACL allows but gates behind an
+ * approval is in this set, because the caller may reach it. Callers that also
+ * need the gate read {@link skillAccess}.
+ */
+export declare function allowedSkillIds(executor: unknown, skillIds: readonly string[], identity: Identity | null): Set<string>;
+/**
+ * The public card: what an unauthenticated caller could actually invoke.
+ *
+ * `system.*` is removed unconditionally (srs FR-AGC-003 criteria 12 and 13); the
+ * remaining subtractions are governance-shaped. See the module docstring for why
+ * this is resolved once rather than per caller.
+ */
+export declare function buildPublicCard(card: AgentCard, executor: unknown, registry: RegistryLike | null | undefined): AgentCard;
+/**
+ * The extended card: what the authenticated caller may invoke.
+ *
+ * `requires_approval` skills are kept (srs FR-AGC-004 criterion 2), whether the
+ * gate comes from the module's annotation or from an ACL rule. Only the
+ * authorization axis of the decision filters here — dropping a skill because it
+ * needs a human would report a refusal the ACL never issued.
+ *
+ * `system.*` is kept too (criterion 11), filtered by the ACL like any other
+ * skill: the namespace exclusion is a property of the public card, not of the
+ * skill, and an authenticated management agent the ACL permits must still be
+ * able to discover the surface it is entitled to drive.
+ */
+export declare function buildExtendedCard(card: AgentCard, executor: unknown, identity: Identity | null): AgentCard;
+//# sourceMappingURL=card-visibility.d.ts.map

package/dist/adapters/card-visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-visibility.d.ts","sourceRoot":"","sources":["../../src/adapters/card-visibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED,+DAA+D;AAC/D,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7E,WAAW,CAAC,CACV,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,GAChB,kBAAkB,CAAC;CACvB;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,MAAM,EAAE,CAAC;IACjB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAC;CACtE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAQ7D;AA6CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAwBtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,GAAG,CAAC,MAAM,CAAC,CAEb;AAOD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GACxC,SAAS,CAqBX;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,SAAS,CAGX"}

package/dist/adapters/card-visibility.js

@@ -0,0 +1,237 @@
+import { Context } from "apcore-js";
+import { requiresApproval } from "./skill-mapper.js";
+/**
+ * Agent Card skill visibility — who gets to see which skills.
+ *
+ * apcore's ACL is the authority on who may invoke what, and the discovery
+ * surface reflects that authority rather than ignoring it. Two surfaces, two
+ * answers:
+ *
+ * - the **public** card (srs FR-AGC-003) answers "what may *anyone* call": every
+ *   registered skill, minus apcore's reserved `system.*` management namespace,
+ *   minus those the ACL denies to the anonymous principal, minus those gated
+ *   behind a human. It resolves exactly one identity, so it is computed once when
+ *   the card is built. A per-caller filter here
+ *   would be strictly more accurate and unaffordable: `/.well-known/` is
+ *   auth-exempt by design, so every anonymous request would drive
+ *   `skills.length` calls into the consumer's ACL audit sink, each recording a
+ *   `deny` decision indistinguishable from a real enforcement event, at whatever
+ *   rate the client chooses.
+ *
+ * - the **extended** card (srs FR-AGC-004) answers "what may *you* call": the
+ *   ACL resolved against the authenticated identity, with `requires_approval`
+ *   skills restored — an approval gate is a prompt the caller can satisfy, not a
+ *   refusal. Affordable precisely because that endpoint requires credentials.
+ *
+ * Only the `system.*` subtraction is unconditional. Every other one is
+ * governance-shaped, and with no ACL configured they collapse: the ACL predicates
+ * are empty and the `requires_approval` annotation covers only
+ * `system.control.*`, leaving the six read modules to publish the deployment's
+ * module inventory, health and usage to any anonymous caller. `ACL.discover()`
+ * yields nothing for a missing root by design, so "no ACL at all" is the default
+ * rather than an edge case — which is why the rule that has to hold there keys on
+ * apcore's namespace and not on a governance verdict (srs FR-AGC-003 criteria 12
+ * and 13).
+ *
+ * Authorization and approval are two independent results, not one (apcore
+ * PROTOCOL_SPEC §6.1.6), and this module reads them apart. `ACL.check` folds
+ * them into a boolean that **fails closed** on an approval requirement —
+ * correct for a caller about to execute, wrong for a discovery surface, where it
+ * would delete a skill from the extended card for the one reason FR-AGC-004 says
+ * to keep it. `ACL.checkAccess` carries both axes, so `access` decides
+ * visibility and `approvalRequired` decides only whether the public card is the
+ * right surface.
+ *
+ * Before this module, this binding filtered nothing at all: `buildSkills`
+ * iterated `registry.list()` and never consulted the ACL, so a module the ACL
+ * denied to everyone was still advertised — by id, name, description and full
+ * input schema — to any anonymous caller.
+ *
+ * **Internal module.** The `export` keywords below are module visibility, not a
+ * public contract: `package.json` declares only `"."` in `exports`, so a
+ * consumer cannot deep-import this file at all, and nothing here appears in
+ * `docs/features/public-api.md`. The surface is expected to move —
+ * `allowedSkillIds` already changed meaning once (it now reports the
+ * authorization axis alone, where it used to fold in the approval gate). Depend
+ * on `serve` / `A2AServerFactory` instead.
+ */
+/**
+ * apcore's reserved namespace for the runtime's own management modules (apcore
+ * PROTOCOL_SPEC §6.7) — `system.health.*`, `system.usage.*`, `system.manifest.*`
+ * and, under the second opt-in, `system.control.*`. apcore identifies the
+ * surface by this prefix itself, in `Executor.governanceState()`, so matching on
+ * it conveys apcore's own boundary rather than inventing one.
+ */
+export const SYSTEM_NAMESPACE = "system.";
+/** Whether `skillId` is one of apcore's management modules. */
+export function isSystemSkill(skillId) {
+    return skillId.startsWith(SYSTEM_NAMESPACE);
+}
+/**
+ * The apcore ACL backing `executor`, if one is configured.
+ *
+ * apcore-js exposes `setAcl` but no getter, so this reads the public property
+ * when one appears upstream and falls back to the private field. `null` means
+ * "no ACL configured", which is the common case and leaves every card
+ * unfiltered.
+ */
+export function executorAcl(executor) {
+    for (const key of ["acl", "_acl"]) {
+        const acl = executor?.[key];
+        if (acl && typeof acl.check === "function") {
+            return acl;
+        }
+    }
+    return null;
+}
+/**
+ * An apcore `Context` carrying `identity`, for conditional ACL rules.
+ *
+ * An ACL rule's `conditions` block (`identityTypes`, `roles`) is evaluated
+ * against the context, and the check returns false without one — so a card
+ * filtered with no context would hide every skill a conditional rule allows.
+ * Building the context the same way the executor does is what keeps the card and
+ * the call path agreeing about the same principal.
+ */
+function aclContext(identity) {
+    try {
+        // apcore-js `Context.create` takes positional arguments (identity first),
+        // unlike the Python binding's keyword form. Passing an options object here
+        // would silently produce a context with no identity, and every conditional
+        // rule would then evaluate false — hiding exactly the skills it allows.
+        return Context.create(identity);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `[authorized, approvalRequired]` for one skill, from apcore's ACL.
+ *
+ * Reads `checkAccess` (apcore-js >= 0.28.0, PROTOCOL_SPEC §6.8.1), which reports
+ * the two axes separately. The `check` fallback exists for an ACL that predates
+ * the accessor: there `approval` did not exist as a rule field, so `false` is
+ * not a guess but the only value such an ACL can mean — and a boolean that
+ * already fails closed degrades this surface toward showing less, never more.
+ */
+function decide(acl, callerId, skillId, ctx) {
+    if (typeof acl.checkAccess !== "function") {
+        return [acl.check(callerId, skillId, ctx), false];
+    }
+    const decision = acl.checkAccess(callerId, skillId, ctx);
+    return [decision.access === "allow", decision.approvalRequired === true];
+}
+/**
+ * The skills the ACL permits `identity` to invoke, each mapped to whether
+ * invoking it needs a human first.
+ *
+ * With no ACL configured every id is permitted and none is gated, which is what
+ * makes this free for the common single-tenant deployment.
+ *
+ * The ACL is consulted with **no arguments projection**, because a card is
+ * discovery and there is no call site yet. An `arguments` condition (§6.1.7) is
+ * therefore unevaluable, so a rule carrying one neither denies nor grants — but
+ * an `allow` rule's `approval: required` stays *pending* and composes with
+ * whatever grants (§6.1.1 rule 5). A skill gated only for some argument shapes
+ * thus reports `true` here: at discovery time "this may need approval" is the
+ * honest answer, and it is the one that keeps such a skill off the public card.
+ *
+ * `callerId` is left `null` deliberately. apcore defines it as the *calling
+ * module* in a nested call chain, managed by `Context.child`; a top-level
+ * inbound request has none, and the ACL maps `null` to `@external`. That is
+ * apcore's contract, not a gap — `callers: ["@external"]` is how an operator
+ * denies external access, and it has to keep matching an authenticated request
+ * or the rule silently stops covering the traffic it was written for. The
+ * authenticated principal travels in the context instead, where the
+ * `identityTypes` / `roles` conditions see it.
+ */
+export function skillAccess(executor, skillIds, identity) {
+    const access = new Map();
+    const acl = executorAcl(executor);
+    if (acl === null) {
+        for (const skillId of skillIds)
+            access.set(skillId, false);
+        return access;
+    }
+    const base = aclContext(identity);
+    for (const skillId of skillIds) {
+        const ctx = base && typeof base.child === "function"
+            ? base.child(skillId)
+            : undefined;
+        const callerId = ctx?.callerId ?? null;
+        try {
+            const [authorized, approvalRequired] = decide(acl, callerId, skillId, ctx);
+            if (authorized)
+                access.set(skillId, approvalRequired);
+        }
+        catch {
+            // A broken ACL must fail closed: serving MORE than the policy allows is
+            // the one outcome that cannot be walked back.
+            console.warn(`ACL check raised for skill ${skillId}; withholding it`);
+        }
+    }
+    return access;
+}
+/**
+ * The subset of `skillIds` the ACL authorizes `identity` to invoke.
+ *
+ * The authorization axis alone: a skill the ACL allows but gates behind an
+ * approval is in this set, because the caller may reach it. Callers that also
+ * need the gate read {@link skillAccess}.
+ */
+export function allowedSkillIds(executor, skillIds, identity) {
+    return new Set(skillAccess(executor, skillIds, identity).keys());
+}
+function withSkills(card, keep) {
+    const skills = (card.skills ?? []).filter((skill) => keep.has(skill.id));
+    return { ...card, skills };
+}
+/**
+ * The public card: what an unauthenticated caller could actually invoke.
+ *
+ * `system.*` is removed unconditionally (srs FR-AGC-003 criteria 12 and 13); the
+ * remaining subtractions are governance-shaped. See the module docstring for why
+ * this is resolved once rather than per caller.
+ */
+export function buildPublicCard(card, executor, registry) {
+    // The management namespace goes first and unconditionally: it is the only
+    // subtraction that survives a deployment with no ACL, and skipping the ACL for
+    // these ids also keeps `system.*` out of the audit trail of a decision whose
+    // answer cannot change the outcome.
+    const ids = (card.skills ?? [])
+        .map((skill) => skill.id)
+        .filter((id) => !isSystemSkill(id));
+    const access = skillAccess(executor, ids, null);
+    // Both sources of an approval gate, unioned as PROTOCOL_SPEC §6.9 composes
+    // them: the module's own annotation, and an ACL rule carrying
+    // `approval: required` for this principal. Since apcore 0.28.0 the annotation
+    // is one source among several, so reading it alone would leave a skill on the
+    // public card that an anonymous caller cannot in fact just call.
+    const keep = new Set();
+    for (const [skillId, approvalRequired] of access) {
+        if (approvalRequired)
+            continue;
+        if (registry && requiresApproval(registry.getDefinition(skillId)))
+            continue;
+        keep.add(skillId);
+    }
+    return withSkills(card, keep);
+}
+/**
+ * The extended card: what the authenticated caller may invoke.
+ *
+ * `requires_approval` skills are kept (srs FR-AGC-004 criterion 2), whether the
+ * gate comes from the module's annotation or from an ACL rule. Only the
+ * authorization axis of the decision filters here — dropping a skill because it
+ * needs a human would report a refusal the ACL never issued.
+ *
+ * `system.*` is kept too (criterion 11), filtered by the ACL like any other
+ * skill: the namespace exclusion is a property of the public card, not of the
+ * skill, and an authenticated management agent the ACL permits must still be
+ * able to discover the surface it is entitled to drive.
+ */
+export function buildExtendedCard(card, executor, identity) {
+    const ids = (card.skills ?? []).map((skill) => skill.id);
+    return withSkills(card, allowedSkillIds(executor, ids, identity));
+}
+//# sourceMappingURL=card-visibility.js.map

package/dist/adapters/card-visibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-visibility.js","sourceRoot":"","sources":["../../src/adapters/card-visibility.ts"],"names":[],"mappings":"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"}

package/dist/adapters/errors.d.ts

@@ -1,12 +1,94 @@
+/**
+ * A2A 1.0 `TaskNotFoundError`. Reserved for an unknown task id or one owned by
+ * another principal — deliberately indistinguishable from each other, and no
+ * longer produced for an authorization refusal (see {@link CODE_ACCESS_DENIED}).
+ */
+export declare const CODE_TASK_NOT_FOUND = -32001;
+export declare const CODE_ACCESS_DENIED = -32040;
+export declare const CODE_APPROVAL_DENIED = -32041;
+export declare const CODE_APPROVAL_TIMEOUT = -32042;
+/** Whether an apcore error code is one of the three governance refusals. */
+export declare function isGovernanceRefusal(code: string | undefined): boolean;
 export interface JsonRpcError {
     code: number;
     message: string;
 }
 export declare class ErrorMapper {
+    readonly discloseRefusalReason: boolean;
+    /**
+     * @param discloseRefusalReason Forward apcore's own message for the three
+     *   governance refusal codes instead of the fixed per-class string
+     *   (srs FR-ERR-011). Off by default. The code never changes with the flag —
+     *   what a refusal *is* does not depend on how much a deployment chooses to
+     *   say about it.
+     */
+    constructor(discloseRefusalReason?: boolean);
     /** ErrorFormatter interface for apcore ErrorFormatterRegistry. */
     format(error: unknown, _context?: unknown): Record<string, unknown>;
     toJsonRpcError(error: unknown): JsonRpcError;
+    /**
+     * Caller-facing message for a governance refusal.
+     *
+     * Default: the fixed per-class string. With `discloseRefusalReason`
+     * (srs FR-ERR-011): apcore's own message, through the same sanitizer every
+     * other forwarded message goes through. An empty or whitespace-only apcore
+     * message falls back to the fixed string rather than sending the caller
+     * nothing.
+     */
+    private refusalMessage;
     private handleApcoreError;
     private sanitizeMessage;
 }
+/**
+ * Whether a `SCHEMA_VALIDATION_ERROR` is about something the *server* produced
+ * rather than something the caller sent.
+ *
+ * Reporting an output-validation failure as `-32602 Invalid params` tells the
+ * caller to fix a request that was correct, and the default `aiGuidance` apcore
+ * attaches to `SchemaValidationError` says "Input validation failed" and points
+ * at a `details.errors` field an A2A caller never receives. Those are
+ * server-side defects and belong behind the fixed internal string.
+ *
+ * The direction label apcore puts at the front of the message is the only signal
+ * that exists, so this matches that prefix. Anything unrecognized keeps the
+ * caller-facing detail -- including a module that raises the code itself with
+ * its own wording, whose message srs FR-ERR-002 requires the caller to see.
+ * Failing to recognize a server-side error therefore preserves the previous
+ * behaviour; it never masks a caller-fixable one by mistake.
+ */
+export declare function isServerSideSchemaError(message: string): boolean;
+/**
+ * Whether {@link ErrorMapper.toJsonRpcError} forwards this error's own message
+ * to the caller (sanitized), or replaces it with a fixed per-class string.
+ *
+ * This is the partition that decides whether a message may be *widened* -- with
+ * `aiGuidance`, or anything else. It is deliberately not `userFixable`, which is
+ * a different partition: six apcore codes carry `userFixable === true` while
+ * falling into `handleApcoreError`'s catch-all (`VERSION_CONSTRAINT_INVALID`,
+ * `BINDING_SCHEMA_INFERENCE_FAILED`, `BINDING_SCHEMA_MODE_CONFLICT`,
+ * `BINDING_STRICT_SCHEMA_INCOMPATIBLE`, `DEPENDENCY_NOT_FOUND`,
+ * `DEPENDENCY_VERSION_MISMATCH`), and appending guidance to those would extend
+ * the fixed "Internal server error" string with internal detail that
+ * {@link sanitizeMessage} does not strip (module ids, versions, env-var names,
+ * hostnames). `userFixable` is also settable per-error by the module author,
+ * which would let any module widen any fixed per-class string at will,
+ * including the governance refusals.
+ *
+ * The three governance codes (`ACL_DENIED`, `APPROVAL_DENIED`,
+ * `APPROVAL_TIMEOUT`) are in this partition only when `discloseRefusalReason` is
+ * set — the same flag the mapper branches on, so the two surfaces agree under
+ * either setting.
+ *
+ * `errorMapper message policy matches toJsonRpcError` locks this to the
+ * branching in `ErrorMapper.handleApcoreError` across every apcore error code
+ * and both flag values, so the two cannot drift.
+ */
+export declare function carriesCallerDetail(error: unknown, discloseRefusalReason?: boolean): boolean;
+/**
+ * Strip file paths, traceback lines and excess whitespace from text bound for a
+ * caller, then truncate to 500 characters. Module-level so the task-status
+ * surface (`server/executor.ts`) applies exactly the same redaction as the
+ * JSON-RPC surface.
+ */
+export declare function sanitizeMessage(message: string): string;
 //# sourceMappingURL=errors.d.ts.map

package/dist/adapters/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,WAAW;IACtB,kEAAkE;IAClE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAKnE,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY;IAqB5C,OAAO,CAAC,iBAAiB;IAuDzB,OAAO,CAAC,eAAe;CAOxB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAc1C,eAAO,MAAM,kBAAkB,SAAS,CAAC;AACzC,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAC3C,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAiB5C,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAErE;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,WAAW;IAQV,QAAQ,CAAC,qBAAqB,EAAE,OAAO;IAPnD;;;;;;OAMG;gBACkB,qBAAqB,GAAE,OAAe;IAE3D,kEAAkE;IAClE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAKnE,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY;IAqB5C;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,iBAAiB;IAmEzB,OAAO,CAAC,eAAe;CAGxB;AAaD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,qBAAqB,UAAQ,GAAG,OAAO,CAe1F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvD"}