apcore-a2a 0.6.0 → 0.7.0

package/README.md

@@ -32,6 +32,7 @@ Built on [`@a2a-js/sdk`](https://www.npmjs.com/package/@a2a-js/sdk) and [Express
 - **JWT authentication** — tokens bridged to apcore's Identity context
 - **A2A Explorer UI** — browser UI for discovering and testing skills, with auth bar and cURL generation
 - **Built-in client** — `A2AClient` for calling remote A2A agents
+- **OpenAPI backend** — point the adapter at an OpenAPI 3.0/3.1 document and every operation becomes an A2A Skill, proxied over HTTP, with no apcore project on the other end
 - **CLI support** — `npx apcore-a2a serve` for zero-code startup
 - **Pluggable storage** — swap in Redis or PostgreSQL via the `TaskStore` interface
 - **Observability** — `/health`, `/metrics` endpoints
@@ -40,7 +41,15 @@ Built on [`@a2a-js/sdk`](https://www.npmjs.com/package/@a2a-js/sdk) and [Express
 ## Requirements
 
 - Node.js >= 18.0.0
-- `apcore-js` >= 0.28.0
+- `apcore-js` >= 0.30.0
+- `apcore-toolkit` >= 0.11.1
+
+> **OpenAPI backend.** No extra install. The backend needs apcore-toolkit's
+> `OpenAPIScanner`, `loadSpec` and `HTTPProxyRegistryWriter`, all of which ship in
+> the `apcore-toolkit` dependency above and use the global `fetch` available on
+> Node 18+ — so this package declares no `openapi` optional dependency. (The
+> Python distribution declares an `apcore-a2a[openapi]` extra because there the
+> same three pieces sit behind `apcore-toolkit[http-proxy]`.)
 
 ---
 
@@ -80,6 +89,68 @@ npx apcore-a2a serve --extensions-dir ./extensions --port 3000 --explorer --metr
 npx apcore-a2a serve --extensions-dir ./extensions --auth-type bearer --auth-key mysecret
 ```
 
+### Serve an OpenAPI document as A2A Skills
+
+Point the adapter at an OpenAPI 3.0/3.1 document and every operation becomes a
+skill, proxied over HTTP to the API that published it. No apcore project required
+on the other end.
+
+```bash
+npx apcore-a2a serve \
+  --from-openapi https://petstore3.swagger.io/api/v3/openapi.json \
+  --openapi-prefix petstore \
+  --openapi-header "X-Api-Key: $PETSTORE_SPEC_KEY" \
+  --openapi-no-deprecated
+```
+
+```typescript
+import { openapiBackend, serve } from "apcore-a2a";
+
+const registry = await openapiBackend("https://api.example.com/openapi.json", {
+  prefix: "petstore",       // prepended to every derived module ID
+  baseUrl: "https://api.example.com", // defaults to servers[0].url
+  include: "pets\\..*",     // scanner filters
+  timeout: 30,              // SPEC-FETCH timeout, in SECONDS
+  headers: { "X-Api-Key": process.env.PETSTORE_SPEC_KEY! }, // spec fetch only
+  authHeaderFactory: () => ({ Authorization: `Bearer ${mintToken()}` }), // proxied calls
+});
+
+serve(registry);
+```
+
+Or configure it entirely through the Config Bus:
+
+```yaml
+apcore-a2a:
+  openapi:
+    spec: "https://api.example.com/openapi.json"  # URL, or a path resolved against Config.projectRoot
+    base_url: "https://api.example.com"
+    prefix: petstore
+    include: "pets.*"
+    exclude: "*.internal.*"
+    include_deprecated: false
+    acknowledge_unapproved_writes: false
+    timeout: 30.0            # spec fetch, seconds — never the per-call proxy timeout
+    headers:
+      X-Api-Key: "${PETSTORE_SPEC_KEY}"
+```
+
+Three things are worth knowing before pointing this at a production API:
+
+- **Write operations reach the PUBLIC Agent Card.** apcore-toolkit infers
+  annotations from the HTTP method and never infers `requiresApproval`, so a
+  `POST /charges` is annotated exactly like a `POST /echo` and appears on
+  `/.well-known/agent-card.json`, a route that is auth-exempt by design. The
+  backend logs a warning naming that exposure; close it with an ACL rule carrying
+  `approval: required` (which also withholds the skill from the public card), or
+  record the decision with `acknowledge_unapproved_writes: true`.
+- **`headers` authenticate the spec fetch only.** They are never forwarded to
+  proxied calls: a document is often public while the API behind it is not.
+  Per-request credentials belong in `authHeaderFactory`.
+- **ACL targets move when the upstream renames an operation.** Set `prefix` and
+  write the catch-all deny against the prefix (`targets: ["petstore.*"]`), not
+  against operation names.
+
 ### Call a remote A2A Agent
 
 Use the built-in client to discover and invoke any A2A-compliant agent:

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"}

package/dist/cli.js

@@ -9,9 +9,27 @@ apcore-a2a - A2A Protocol Server for apcore modules
 
 Usage:
   apcore-a2a serve --extensions-dir <path> [options]
+  apcore-a2a serve --from-openapi <url|path> [options]
 
-Required:
+Required (at least one backend source):
   --extensions-dir <path>    Path to apcore extensions directory
+  --from-openapi <url|path>  OpenAPI 3.0/3.1 document to serve as A2A Skills.
+                             Combine with --extensions-dir only when
+                             --openapi-prefix is also given
+
+  An apcore-a2a.openapi.spec in your apcore config counts as a backend source
+  too, so neither flag is required when the config file names one.
+
+OpenAPI backend options (each overrides the matching apcore-a2a.openapi key;
+keys with no flag -- timeout, headers, acknowledge_unapproved_writes -- are
+configured there):
+  --openapi-base-url <url>   Base URL for proxied calls (default: servers[0].url)
+  --openapi-prefix <string>  Prefix for every derived module ID
+  --openapi-include <regex>  Scanner include filter
+  --openapi-exclude <regex>  Scanner exclude filter
+  --openapi-header <K:V>     Header for the SPEC FETCH only, repeatable.
+                             Never forwarded to proxied calls
+  --openapi-no-deprecated    Skip operations marked deprecated: true
 
 Options:
   --host <address>           Bind host (default: 127.0.0.1)
@@ -34,10 +52,32 @@ Options:
   --help                     Show this help
 `);
 }
+/**
+ * Exit `1` — a configuration or runtime error.
+ *
+ * The command line was well-formed; the environment it named was not. A
+ * supervisor may retry these, because the world can become ready.
+ */
 function fail(message, exitCode = 1) {
     console.error(`Error: ${message}`);
     process.exit(exitCode);
 }
+/**
+ * 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 function failUsage(message) {
+    return fail(message, 2);
+}
 export function resolveAuthKey(authKey) {
     if (authKey) {
         try {
@@ -52,37 +92,113 @@ export function resolveAuthKey(authKey) {
     }
     return process.env.APCORE_JWT_SECRET;
 }
+/**
+ * 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 function parseCliArgs(args) {
+    const config = {
+        options: {
+            "extensions-dir": { type: "string" },
+            "from-openapi": { type: "string" },
+            "openapi-base-url": { type: "string" },
+            "openapi-prefix": { type: "string" },
+            "openapi-include": { type: "string" },
+            "openapi-exclude": { type: "string" },
+            "openapi-header": { type: "string", multiple: true },
+            // Deliberately NO `default: false`. `mergeOpenapiSettings` has to tell
+            // "not passed" from "passed", because a `false` default would make an
+            // absent flag overwrite a config `include_deprecated: false` with `true`
+            // — an unpassed flag silently reversing a setting the operator wrote.
+            // Same reason the Python binding uses `default=None`.
+            "openapi-no-deprecated": { type: "boolean" },
+            host: { type: "string", default: "127.0.0.1" },
+            port: { type: "string", default: "8000" },
+            name: { type: "string" },
+            description: { type: "string" },
+            "version-str": { type: "string" },
+            url: { type: "string" },
+            "auth-type": { type: "string" },
+            "auth-key": { type: "string" },
+            "auth-issuer": { type: "string" },
+            "auth-audience": { type: "string" },
+            "push-notifications": { type: "boolean", default: false },
+            explorer: { type: "boolean", default: false },
+            "cors-origins": { type: "string" },
+            "execution-timeout": { type: "string", default: "300" },
+            "log-level": { type: "string", default: "info" },
+            metrics: { type: "boolean", default: false },
+            version: { type: "boolean", default: false },
+            help: { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+        strict: false,
+    };
+    // `args: undefined` is NOT the same as omitting it — node's own default
+    // (`process.argv` minus the execPath and script) knows about `node --` and
+    // single-executable builds, and re-deriving it here would drop that.
+    const parsed = args === undefined ? parseArgs(config) : parseArgs({ ...config, args });
+    rejectUnknownArguments(parsed, Object.keys(config.options));
+    return parsed;
+}
+/**
+ * Refuse an argument the flag table does not define.
+ *
+ * `strict: false` is kept deliberately — it is what lets this CLI tolerate
+ * `--metrics=x` for a boolean and a repeat of a non-`multiple` option, both of
+ * which `strict: true` would turn into throws — but node's tolerance extends to
+ * *unknown* flags too, and there it is not tolerance, it is silence.
+ *
+ * Measured before this check existed, with a one-letter typo:
+ *
+ * ```
+ * apcore-a2a serve --extensions-dir ./ext --openapi-exclde 'secret.*'
+ *   values:      { "openapi-exclde": true, ... }   ← the flag became a boolean
+ *   positionals: [ "serve", "secret.*" ]           ← its value became a positional
+ * ```
+ *
+ * The exclusion silently did not apply, and every operation it was meant to hold
+ * back was scanned, registered, and published to the **public** Agent Card — a
+ * route served without authentication and built to be crawled. The server
+ * started and reported success.
+ *
+ * Python's argparse (`unrecognized arguments`) and Rust's clap (`unexpected
+ * argument ... found`) both refuse this and exit 2; TypeScript was the only
+ * binding that did not, so the tolerant behaviour was never portable — the same
+ * argv already failed on the other two.
+ *
+ * Note argparse additionally accepts unambiguous *abbreviations*, so
+ * `--openapi-exclud` is a legal spelling there. That is an argparse feature, not
+ * a parity requirement: clap does not do it either, and this check is only about
+ * spellings no binding recognises.
+ */
+function rejectUnknownArguments(parsed, known) {
+    const unknown = Object.keys(parsed.values).filter((key) => !known.includes(key));
+    if (unknown.length > 0) {
+        failUsage(`unrecognized argument${unknown.length > 1 ? "s" : ""}: ` +
+            `${unknown.map((k) => `--${k}`).join(", ")}. Run with --help for the flag list`);
+    }
+    // A stray positional is the same mistake seen from the other side: the value
+    // of a misspelled flag lands here, so reporting only the flag would leave the
+    // operator wondering where their argument went.
+    const strays = parsed.positionals.slice(1);
+    if (strays.length > 0) {
+        failUsage(`unexpected argument${strays.length > 1 ? "s" : ""}: ${strays.join(", ")}. ` +
+            "Run with --help for the flag list");
+    }
+}
 export async function main() {
     let parsed;
     try {
-        parsed = parseArgs({
-            options: {
-                "extensions-dir": { type: "string" },
-                host: { type: "string", default: "127.0.0.1" },
-                port: { type: "string", default: "8000" },
-                name: { type: "string" },
-                description: { type: "string" },
-                "version-str": { type: "string" },
-                url: { type: "string" },
-                "auth-type": { type: "string" },
-                "auth-key": { type: "string" },
-                "auth-issuer": { type: "string" },
-                "auth-audience": { type: "string" },
-                "push-notifications": { type: "boolean", default: false },
-                explorer: { type: "boolean", default: false },
-                "cors-origins": { type: "string" },
-                "execution-timeout": { type: "string", default: "300" },
-                "log-level": { type: "string", default: "info" },
-                metrics: { type: "boolean", default: false },
-                version: { type: "boolean", default: false },
-                help: { type: "boolean", default: false },
-            },
-            allowPositionals: true,
-            strict: false,
-        });
+        parsed = parseCliArgs();
     }
     catch (e) {
-        fail(String(e));
+        // A parseArgs throw is an unknown flag or a missing value: a usage fault.
+        failUsage(String(e));
     }
     const { values, positionals } = parsed;
     if (values.help) {
@@ -101,24 +217,149 @@ export async function main() {
     }
     await runServe(values);
 }
+/**
+ * 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 function parseOpenapiHeaders(raw) {
+    if (!raw || raw.length === 0)
+        return undefined;
+    const headers = {};
+    for (const entry of raw) {
+        const separator = entry.indexOf(":");
+        // The separator index alone is not the test. `separator <= 0` rejects ":v"
+        // but ACCEPTS " :v" — the colon is at index 1 — and the `.trim()` below then
+        // yields an EMPTY header name. Python checks `not key.strip()` and Rust
+        // `key.trim().is_empty()`; both reject, so the key is trimmed first and
+        // judged afterwards.
+        const key = separator > 0 ? entry.slice(0, separator).trim() : "";
+        if (!key) {
+            // Never echo the value back: the whole point of the flag is that it may
+            // carry a credential.
+            failUsage(`--openapi-header must be "Key: Value" (got an entry with no ':' or no key)`);
+        }
+        headers[key] = entry.slice(separator + 1).trim();
+    }
+    return headers;
+}
+/**
+ * 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 async function mergeOpenapiSettings(values) {
+    // Imported lazily so `--help` and `--version` never pay for loading apcore's
+    // Config, mirroring the Python binding's function-local import.
+    const { getA2aSetting } = await import("./config.js");
+    const section = getA2aSetting("openapi");
+    // A section that is not a mapping is passed through untouched, so that
+    // `buildOpenapiBackendFromConfig` reports it by name ("apcore-a2a.openapi
+    // must be a mapping."). Discarding it instead would turn the typo
+    // `openapi: ./spec.json` — a mapping's one key written as the whole value —
+    // into "a backend source is required", which sends the operator hunting for a
+    // missing flag rather than at the line they wrote. Follows the Rust binding,
+    // which diverged from the Python reference here for this reason.
+    if (section !== undefined && (typeof section !== "object" || Array.isArray(section))) {
+        return section;
+    }
+    const merged = {
+        ...(section ?? {}),
+    };
+    // Only a flag the operator actually passed is overlaid. Every OpenAPI flag is
+    // `undefined` when absent precisely so that "absent" stays distinguishable
+    // from "explicitly set to a falsy value".
+    const overlay = {
+        spec: values["from-openapi"],
+        base_url: values["openapi-base-url"],
+        prefix: values["openapi-prefix"],
+        include: values["openapi-include"],
+        exclude: values["openapi-exclude"],
+        headers: parseOpenapiHeaders(values["openapi-header"]),
+    };
+    if (values["openapi-no-deprecated"] !== undefined) {
+        overlay.include_deprecated = !values["openapi-no-deprecated"];
+    }
+    for (const [key, value] of Object.entries(overlay)) {
+        if (value !== undefined && value !== null)
+            merged[key] = value;
+    }
+    return merged.spec ? merged : null;
+}
+/** The `spec` of merged settings, when they are a mapping that names one. */
+function specOf(openapi) {
+    if (typeof openapi !== "object" || openapi === null)
+        return undefined;
+    const spec = openapi.spec;
+    return typeof spec === "string" ? spec : undefined;
+}
 async function runServe(values) {
     const extensionsDir = values["extensions-dir"];
-    if (!extensionsDir) {
-        fail("--extensions-dir is required");
+    // A backend source may also come from the Config Bus, so the usage check has
+    // to consult it — otherwise a valid `apcore-a2a.openapi.spec` in the config
+    // file would be rejected for naming no flag.
+    const openapi = await mergeOpenapiSettings(values);
+    if (!extensionsDir && !openapi) {
+        failUsage("one of --extensions-dir or --from-openapi is required " +
+            "(or an apcore-a2a.openapi.spec in your apcore config)");
+    }
+    const { Registry } = await import("apcore-js");
+    let registry;
+    if (extensionsDir) {
+        const resolved = resolve(extensionsDir);
+        if (!existsSync(resolved)) {
+            fail(`Extensions directory not found: ${resolved}`);
+        }
+        if (!statSync(resolved).isDirectory()) {
+            fail(`Not a directory: ${resolved}`);
+        }
+        registry = new Registry({ extensionsDir: resolved });
     }
-    const resolved = resolve(extensionsDir);
-    if (!existsSync(resolved)) {
-        fail(`Extensions directory not found: ${resolved}`);
+    else {
+        registry = new Registry();
     }
-    if (!statSync(resolved).isDirectory()) {
-        fail(`Not a directory: ${resolved}`);
+    if (openapi) {
+        const { buildOpenapiBackendFromConfig } = await import("./openapi-backend.js");
+        try {
+            // The merged mapping, not the raw flags: this is the one route that reads
+            // `timeout` and `acknowledge_unapproved_writes`, applies the documented
+            // defaults, and resolves a relative `spec` against `Config.projectRoot`
+            // rather than the process CWD (FR-OAS-004 AC 5).
+            registry =
+                (await buildOpenapiBackendFromConfig(openapi, {
+                    registry,
+                    // `prefix` is mandatory in a mixed deployment: the scanner
+                    // deduplicates within one scan only and knows nothing about the
+                    // project modules already in the registry.
+                    hasOtherBackendSource: !!extensionsDir,
+                })) ?? registry;
+        }
+        catch (e) {
+            // The resolved spec location may appear here; the fetch headers never do.
+            fail(`OpenAPI backend: ${e instanceof Error ? e.message : String(e)}`);
+        }
     }
-    // Load registry
-    const { Registry } = await import("apcore-js");
-    const registry = new Registry({ extensionsDir: resolved });
     const modules = registry.list();
     if (modules.length === 0) {
-        fail(`No modules discovered in ${resolved}`);
+        fail(`No modules discovered in ${specOf(openapi) ?? extensionsDir}`);
     }
     console.log(`Discovered ${modules.length} module(s): ${modules.join(", ")}`);
     // Build auth

package/dist/cli.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Config namespace registration and resolution for `apcore-a2a`.
+ *
+ * Mirrors the Python binding's `apcore_a2a._config`. It lives in its own module
+ * rather than in `server/factory.ts` because the CLI has to read the
+ * `apcore-a2a.openapi` section *before* it builds a Registry, and therefore long
+ * before anything in the server stack is imported — pulling in the factory (and
+ * with it express and the whole A2A SDK) just to register a namespace would put
+ * the entire server on the startup path of `apcore-a2a serve --help`.
+ *
+ * Registration must happen from exactly ONE place: apcore's
+ * `Config.registerNamespace` throws `ConfigNamespaceDuplicateError` on a second
+ * call for the same name, so a second registration site would crash the process
+ * at import time rather than being ignored.
+ */
+export declare const A2A_NAMESPACE = "apcore-a2a";
+export declare const A2A_ENV_PREFIX = "APCORE_A2A";
+/** The registered namespace defaults (stable in apcore-js >= 0.22.0). */
+export declare const A2A_DEFAULTS: Record<string, unknown>;
+/**
+ * Register the `apcore-a2a` config namespace. Safe to call repeatedly.
+ *
+ * The already-registered case is detected rather than caught: swallowing every
+ * exception here would also swallow a genuine `ConfigEnvPrefixConflictError`
+ * from another package claiming `APCORE_A2A`, which is a misconfiguration the
+ * operator needs to see.
+ */
+export declare function registerA2aNamespace(): void;
+/**
+ * Resolve one `apcore-a2a` namespace setting through apcore's Config.
+ *
+ * Delegates to `Config.load` so that values from an apcore config file and
+ * `APCORE_A2A_*` environment overrides are applied by apcore itself (namespace
+ * mode), exactly like the other apcore bindings. Falls back to `fallback` when
+ * the key is unset.
+ */
+export declare function getA2aSetting(key: string, fallback?: unknown): unknown;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,eAAO,MAAM,aAAa,eAAe,CAAC;AAC1C,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C,yEAAyE;AACzE,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAoBhD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAO3C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAMtE"}