apcore-a2a 0.5.0 → 0.7.0

package/dist/adapters/errors.js

@@ -2,8 +2,57 @@ import { ErrorCodes } from "apcore-js";
 const CODE_METHOD_NOT_FOUND = -32601;
 const CODE_INVALID_PARAMS = -32602;
 const CODE_INTERNAL_ERROR = -32603;
-const CODE_TASK_NOT_FOUND = -32001;
+/**
+ * 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 const CODE_TASK_NOT_FOUND = -32001;
+// Governance refusal codes (srs FR-ERR-003 / FR-ERR-009 / FR-ERR-010).
+//
+// A2A 1.0 reserves -32001..-32009; JSON-RPC 2.0 leaves -32000..-32099 to the
+// implementation. These three sit above A2A's reserved block, with room for it
+// to grow, and are the "JSON-RPC custom error" A2A §13.2 names as the example
+// for this binding.
+//
+// apcore distinguishes these three refusals from each other and from every
+// other failure. Collapsing them onto -32001 (which means "unknown or non-owned
+// task id") or -32603 (which every agent reads as "retry me") told the caller a
+// *different* failure had happened, one whose correct response is the opposite
+// of the real one.
+export const CODE_ACCESS_DENIED = -32040;
+export const CODE_APPROVAL_DENIED = -32041;
+export const CODE_APPROVAL_TIMEOUT = -32042;
+/**
+ * The three governance refusal codes, each with its JSON-RPC code and the fixed
+ * message it reports by default.
+ *
+ * `APPROVAL_PENDING` is deliberately absent: it is a resumable pause carrying
+ * the `approvalId` the caller resumes with, handled by the executor before it
+ * ever reaches the mapper (srs FR-EXE-002). Sweeping it in here would turn that
+ * pause into a terminal failure.
+ */
+const GOVERNANCE_REFUSALS = new Map([
+    [ErrorCodes.ACL_DENIED, { code: CODE_ACCESS_DENIED, message: "Access denied" }],
+    [ErrorCodes.APPROVAL_DENIED, { code: CODE_APPROVAL_DENIED, message: "Approval denied" }],
+    [ErrorCodes.APPROVAL_TIMEOUT, { code: CODE_APPROVAL_TIMEOUT, message: "Approval timed out" }],
+]);
+/** Whether an apcore error code is one of the three governance refusals. */
+export function isGovernanceRefusal(code) {
+    return code !== undefined && GOVERNANCE_REFUSALS.has(code);
+}
 export class ErrorMapper {
+    discloseRefusalReason;
+    /**
+     * @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 = false) {
+        this.discloseRefusalReason = discloseRefusalReason;
+    }
     /** ErrorFormatter interface for apcore ErrorFormatterRegistry. */
     format(error, _context) {
         const rpcError = this.toJsonRpcError(error);
@@ -25,6 +74,21 @@ export class ErrorMapper {
         }
         return { code: CODE_INTERNAL_ERROR, message: "Internal server error" };
     }
+    /**
+     * 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.
+     */
+    refusalMessage(fixed, error) {
+        if (!this.discloseRefusalReason)
+            return fixed;
+        const disclosed = this.sanitizeMessage(String(error.message ?? ""));
+        return disclosed.trim() ? disclosed : fixed;
+    }
     handleApcoreError(error, errorCode) {
         if (errorCode === ErrorCodes.MODULE_NOT_FOUND) {
             const message = this.sanitizeMessage(error.message);
@@ -43,8 +107,15 @@ export class ErrorMapper {
             const description = this.sanitizeMessage(error.message);
             return { code: CODE_INVALID_PARAMS, message: `Invalid input: ${description}` };
         }
-        if (errorCode === ErrorCodes.ACL_DENIED) {
-            return { code: CODE_TASK_NOT_FOUND, message: "Task not found" };
+        // The A2A spec §13.2 MUST NOT forbids revealing *the existence of a
+        // resource*, not the *class* of failure. A fixed "Access denied" /
+        // "Approval denied" / "Approval timed out" names no caller, target,
+        // approver or rule, so it discloses nothing — a caller that named a skill
+        // already held that id — while still telling an agent to stop rather than
+        // retry.
+        const refusal = GOVERNANCE_REFUSALS.get(errorCode);
+        if (refusal !== undefined) {
+            return { code: refusal.code, message: this.refusalMessage(refusal.message, error) };
         }
         if (errorCode === ErrorCodes.MODULE_TIMEOUT) {
             return { code: CODE_INTERNAL_ERROR, message: "Execution timeout" };
@@ -119,13 +190,18 @@ export function isServerSideSchemaError(message) {
  * {@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 `ACL_DENIED` mask.
+ * 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,
- * so the two cannot drift.
+ * branching in `ErrorMapper.handleApcoreError` across every apcore error code
+ * and both flag values, so the two cannot drift.
  */
-export function carriesCallerDetail(error) {
+export function carriesCallerDetail(error, discloseRefusalReason = false) {
     const code = error?.code;
     if (code === ErrorCodes.MODULE_NOT_FOUND || code === ErrorCodes.GENERAL_INVALID_INPUT) {
         return true;
@@ -133,6 +209,12 @@ export function carriesCallerDetail(error) {
     if (code === ErrorCodes.SCHEMA_VALIDATION_ERROR) {
         return !isServerSideSchemaError(String(error.message ?? ""));
     }
+    // The three governance codes move into and out of this partition with the
+    // flag, so the task-status surface forwards exactly what the JSON-RPC surface
+    // does under either setting (srs FR-ERR-011 criterion 4).
+    if (isGovernanceRefusal(code)) {
+        return discloseRefusalReason;
+    }
     return false;
 }
 /**

package/dist/adapters/errors.js.map

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

package/dist/adapters/skill-mapper.d.ts

@@ -15,6 +15,33 @@ export interface ModuleDescriptor {
     annotations?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Append apcore's behavioral annotations to a skill's tags (srs FR-SKL-004).
+ *
+ * A2A 1.0 `AgentSkill` is `{id, name, description, tags, examples, inputModes,
+ * outputModes, securityRequirements}` — no `extensions`, no `metadata` — so
+ * `tags` is the only carrier that exists. The `apcore:` prefix keeps these out
+ * of the module's own flat tag namespace, where a user tag named `destructive`
+ * would otherwise be indistinguishable from the annotation.
+ *
+ * Without this the Agent Card carried enough for a caller to *construct* a call
+ * and not enough to judge whether making it is safe. It is also what makes retry
+ * semantics usable: `retryable` is a property of the error, but whether a retry
+ * is safe is a property of the operation, and a timeout is retryable for a read
+ * and dangerous for a non-idempotent mutation.
+ *
+ * Only truthy flags are emitted, matching how the apcore MCP binding maps the
+ * same annotations onto optional `readOnlyHint` / `destructiveHint` /
+ * `idempotentHint`. Absence means "not asserted", never "asserted false".
+ */
+export declare function appendAnnotationTags(tags: string[], descriptor: ModuleDescriptor): void;
+/**
+ * Whether a module is gated behind human approval.
+ *
+ * Used by the Agent Card builder to withhold the skill from the public card
+ * (srs FR-AGC-003) and restore it on the extended one (srs FR-AGC-004).
+ */
+export declare function requiresApproval(descriptor: ModuleDescriptor | null | undefined): boolean;
 export declare class SkillMapper {
     private schemaConverter;
     constructor(schemaConverter?: SchemaConverter);

package/dist/adapters/skill-mapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-mapper.d.ts","sourceRoot":"","sources":["../../src/adapters/skill-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAmB,MAAM,aAAa,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qBAAa,WAAW;IAGV,OAAO,CAAC,eAAe;gBAAf,eAAe,GAAE,eAAuC;IAE5E,OAAO,CAAC,UAAU,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IA2C3E,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAO1C,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,kBAAkB;IAM1B,aAAa,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,EAAE;CAQtD"}
+{"version":3,"file":"skill-mapper.d.ts","sourceRoot":"","sources":["../../src/adapters/skill-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAmB,MAAM,aAAa,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAwBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAQvF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAIzF;AAED,qBAAa,WAAW;IAGV,OAAO,CAAC,eAAe;gBAAf,eAAe,GAAE,eAAuC;IAE5E,OAAO,CAAC,UAAU,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IA4C3E,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAO1C,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,kBAAkB;IAM1B,aAAa,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,EAAE;CAQtD"}

package/dist/adapters/skill-mapper.js

@@ -1,4 +1,64 @@
 import { SchemaConverter } from "./schema.js";
+/**
+ * The four behavioral annotations promoted onto the A2A wire, with the tag each
+ * becomes. Order is fixed so the card is byte-identical across the three
+ * bindings (srs FR-SKL-004 criterion 8).
+ */
+const ANNOTATION_TAGS = [
+    ["readonly", "apcore:readonly"],
+    ["destructive", "apcore:destructive"],
+    ["idempotent", "apcore:idempotent"],
+    ["requires_approval", "apcore:requires-approval"],
+];
+/** camelCase aliases, since a descriptor may arrive from either convention. */
+const ANNOTATION_ALIASES = {
+    requires_approval: "requiresApproval",
+};
+function annotationFlag(annotations, field) {
+    const alias = ANNOTATION_ALIASES[field];
+    return Boolean(annotations[field] ?? (alias !== undefined ? annotations[alias] : undefined));
+}
+/**
+ * Append apcore's behavioral annotations to a skill's tags (srs FR-SKL-004).
+ *
+ * A2A 1.0 `AgentSkill` is `{id, name, description, tags, examples, inputModes,
+ * outputModes, securityRequirements}` — no `extensions`, no `metadata` — so
+ * `tags` is the only carrier that exists. The `apcore:` prefix keeps these out
+ * of the module's own flat tag namespace, where a user tag named `destructive`
+ * would otherwise be indistinguishable from the annotation.
+ *
+ * Without this the Agent Card carried enough for a caller to *construct* a call
+ * and not enough to judge whether making it is safe. It is also what makes retry
+ * semantics usable: `retryable` is a property of the error, but whether a retry
+ * is safe is a property of the operation, and a timeout is retryable for a read
+ * and dangerous for a non-idempotent mutation.
+ *
+ * Only truthy flags are emitted, matching how the apcore MCP binding maps the
+ * same annotations onto optional `readOnlyHint` / `destructiveHint` /
+ * `idempotentHint`. Absence means "not asserted", never "asserted false".
+ */
+export function appendAnnotationTags(tags, descriptor) {
+    const annotations = descriptor.annotations;
+    if (!annotations)
+        return;
+    for (const [field, tag] of ANNOTATION_TAGS) {
+        if (annotationFlag(annotations, field) && !tags.includes(tag)) {
+            tags.push(tag);
+        }
+    }
+}
+/**
+ * Whether a module is gated behind human approval.
+ *
+ * Used by the Agent Card builder to withhold the skill from the public card
+ * (srs FR-AGC-003) and restore it on the extended one (srs FR-AGC-004).
+ */
+export function requiresApproval(descriptor) {
+    const annotations = descriptor?.annotations;
+    if (!annotations)
+        return false;
+    return annotationFlag(annotations, "requires_approval");
+}
 export class SkillMapper {
     schemaConverter;
     // Share root-type detection with SchemaConverter so the "string root" rule
@@ -29,6 +89,7 @@ export class SkillMapper {
         const resolvedTags = display.tags?.length
             ? [...display.tags]
             : [...(descriptor.tags ?? [])];
+        appendAnnotationTags(resolvedTags, descriptor);
         return {
             id,
             name: skillName,

package/dist/adapters/skill-mapper.js.map

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

package/dist/cli.d.ts

@@ -1,4 +1,67 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
+/**
+ * The `values` half of a `parseArgs` result under `strict: false`.
+ *
+ * Wider than the flag table suggests on purpose: with `strict: false` node
+ * accepts `--metrics=x` for a boolean and repeats for a non-`multiple` option,
+ * so every entry may arrive as a string, a boolean, or an array of either.
+ */
+type CliValues = Record<string, string | boolean | (string | boolean)[] | undefined>;
+/**
+ * Exit `2` — a usage error. The command line itself is wrong.
+ *
+ * Distinguished from {@link fail} because retrying an exit-2 command unchanged
+ * will always fail, while an exit-1 command may succeed once the directory,
+ * config or network it named is fixed. That is a difference a supervisor or CI
+ * job can act on, and this SDK previously collapsed both onto `1` — losing a
+ * distinction Python's argparse and Rust's clap each provide for free.
+ *
+ * `2` rather than some other number because it is what argparse, clap and GNU
+ * getopt all use for a usage fault, so the three bindings agree with each other
+ * and with the tools around them.
+ */
+export declare function failUsage(message: string): never;
 export declare function resolveAuthKey(authKey?: string): string | undefined;
+/**
+ * Parse `serve`'s argv.
+ *
+ * Split out of {@link main} so the flag surface is reachable without starting a
+ * server: the `--openapi-no-deprecated` contract is half in this table (no
+ * `default`) and half in {@link mergeOpenapiSettings} (the presence check), and
+ * either half alone silently reverses a config `include_deprecated: false`.
+ */
+export declare function parseCliArgs(args?: string[]): ReturnType<typeof parseArgs>;
 export declare function main(): Promise<void>;
+/**
+ * Parse repeated `--openapi-header "Key: Value"` flags into a header map.
+ *
+ * These authenticate the **spec fetch only**. They are deliberately not reused
+ * for proxied calls: a document is often public while the API behind it is not,
+ * and broadcasting a spec-read key on every skill invocation would be a
+ * privilege escalation the operator never wrote down.
+ */
+export declare function parseOpenapiHeaders(raw: string[] | undefined): Record<string, string> | undefined;
+/**
+ * Resolve the OpenAPI backend settings: CLI flags over the Config Bus.
+ *
+ * Implements the precedence the feature spec states — **an explicit CLI flag
+ * beats the `apcore-a2a.openapi` Config Bus section, which beats the default** —
+ * and implements it PER KEY, not per source. Choosing the whole source by
+ * whoever named `spec` would make a `--openapi-prefix` alongside a
+ * config-declared `spec` a silent no-op: the same shape as the apcore-mcp
+ * `--openapi-header` defect this project filed upstream (apcore-mcp-rust#8).
+ *
+ * The returned mapping is in the Config Bus's own snake_case, so it can be
+ * handed straight to `buildOpenapiBackendFromConfig` — which is also what makes
+ * `timeout`, `include`, `exclude` and `acknowledge_unapproved_writes` reachable
+ * from a running server: none of them has a CLI flag, and before this the
+ * section had no reader anywhere in `src/`.
+ *
+ * Returns `null` when neither route yields a `spec`, which is the ordinary "no
+ * OpenAPI configured" outcome rather than an error. A section that is not a
+ * mapping is returned UNCHANGED — see below.
+ */
+export declare function mergeOpenapiSettings(values: CliValues): Promise<unknown>;
+export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA4CA,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYnE;AAED,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAsD1C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAKA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAqDtC;;;;;;GAMG;AACH,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC;AAarF;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAEhD;AAED,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYnE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CA6C1E;AAwDD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA+B1C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAS,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAmBpC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAuC9E"}