@akai-workflow-builder/cli-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The @akai-workflow-builder/cli-sdk Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,370 @@
+# @akai-workflow-builder/cli-sdk
+
+> Author atomic, agent-executable CLIs in TypeScript.
+
+A small, opinionated SDK for defining CLIs that an agent runtime invokes. Each tool represents one atomic operation — typically a single HTTP call, but a tool can wrap any single observable operation. The SDK gives you a sandboxed `fetch`, scoped secrets, typed input + output schemas, and a per-tool egress allowlist. The host runtime handles input validation, secret scoping, network sandboxing, and the human-in-the-loop approval gate for writes.
+
+> **Status:** pre-v0.1. The authoring surface (`tool`, `defineCLI`, `buildCtx`, `ctx.fetch`, `ctx.secrets`, `ctx.properties`) is stable.
+
+---
+
+## Installation
+
+```bash
+npm install @akai/cli zod
+```
+
+## Requirements
+
+| | |
+|---|---|
+| Node          | `≥ 24` |
+| TypeScript    | `≥ 5.0` (uses `const` type parameters for literal-key inference) |
+| `zod`         | `^4.4.1` (peer dependency) |
+| `tsconfig.json` | needs `Response` / `RequestInit` / `AbortSignal`. Either add `"DOM"` to your existing `lib` entries (e.g. `"lib": ["ES2023", "DOM"]`) or include `@types/node@^18+` |
+
+---
+
+## Quickstart
+
+```ts
+import { tool, defineCLI } from '@akai/cli';
+import { z } from 'zod';
+
+// Define the response shape once; reuse for `jsonOutput` and runtime parsing.
+const Response = z.object({
+  user: z.object({ id: z.number(), email: z.string() }),
+});
+
+const usersMe = tool({
+  name: 'Authenticated user',
+  description: 'Return the authenticated user.',
+  jsonOutput: Response,                          // input defaults to z.object({}) when omitted
+  options: {
+    network: { egress: 'zendesk.com' },
+    secretKeys: ['ZENDESK_SUBDOMAIN', 'ZENDESK_API_TOKEN'],
+    isReadonly: true,
+  },
+  handler: async ({ ctx, isJson }) => {
+    const sub = ctx.secrets.ZENDESK_SUBDOMAIN!;
+    const tok = ctx.secrets.ZENDESK_API_TOKEN!;
+    // Quickstart trusts `sub` is a workspace shortname ("acme"); the worked
+    // example validates it before constructing the URL.
+    const res = await ctx.fetch(`https://${sub}.zendesk.com/api/v2/users/me.json`, {
+      signal: ctx.signal,
+      headers: { Authorization: `Bearer ${tok}` },
+    });
+    if (!res.ok) throw new Error(`fetch authenticated user failed: ${res.status}`);
+    // Parse, don't cast — strips unknown fields, throws if the shape changes.
+    const body = Response.parse(await res.json());
+    return isJson ? body : `User #${body.user.id} <${body.user.email}>`;
+  },
+});
+
+export default defineCLI({
+  id: 'zendesk',
+  name: 'Zendesk Support',
+  summary: 'Read tickets, users, and search results from Zendesk Support.',
+  description:
+    'Connect to a Zendesk Support workspace via OAuth bearer token. Read-only surface: fetch the authenticated user, fetch tickets and users by id, list tickets, and run search queries.',
+  secrets: [
+    { key: 'ZENDESK_SUBDOMAIN', name: 'Workspace subdomain', description: '...', required: true },
+    { key: 'ZENDESK_API_TOKEN', name: 'API access token',    description: '...', required: true },
+  ],
+  tools: {
+    'users.me': usersMe,
+  },
+});
+```
+
+A full worked example with five read-only tools and a smoke runner lives in the repository under `examples/zendesk/` (not bundled in the published package; see the source tree).
+
+---
+
+## Core concepts
+
+### Atomic tools
+
+Every `tool()` represents **one atomic operation** — typically a single HTTP call, but it can wrap any single observable operation (a local compute, a file read, a DB query). Composition is the planner's responsibility — agents plan over the atomic tools the runtime exposes; the SDK is intentionally not the place to chain steps.
+
+Three consequences:
+
+- **Per-tool permissions are meaningful** — one tool = one observable side effect = one approval surface.
+- **Schemas stay tight** — each tool documents one operation, not a workflow.
+- **No hidden side effects** — what the schema describes is what executes.
+
+The SDK doesn't statically enforce step count — atomicity is a design guideline. If a logical step needs three calls, ship three tools and let the planner compose them.
+
+### `defineCLI()`
+
+A CLI is a named bundle of tools sharing one secret-declaration set:
+
+```ts
+defineCLI({
+  id: 'zendesk',
+  name: 'Zendesk Support',
+  summary: 'Read tickets, users, and search results from Zendesk Support.',
+  description: 'Connect to a Zendesk Support workspace via OAuth bearer token …',
+  secrets: [/* ... */],
+  tools: {
+    'users.me':     usersMe,
+    'tickets.get':  getTicket,
+    'tickets.list': listTickets,
+  },
+});
+```
+
+**Required**
+
+| Field | Role |
+|---|---|
+| `id`      | Machine slug. Used for wire ids (`<id>.<toolKey>`) and the `x-akai-cli` header. Pattern: `^[a-z][a-z0-9_-]*$`. |
+| `name`    | Human display label. |
+| `summary` | One-sentence short label. |
+| `tools`   | Map of `tool()` results. Keys follow the kebab + dotted convention below. |
+
+**Optional**
+
+| Field | Role |
+|---|---|
+| `vendor`       | Brand/company. Defaults to `name`. Useful when display ("JPMorgan Access Portal") differs from vendor ("JPMorgan"). |
+| `description`  | Long-form description. Consumers decide how to render when omitted. |
+| `instructions` | Ordered setup steps shown to operators. |
+| `secrets`      | Array of `SecretDecl` (the keys tools reference). |
+| `properties`   | Array of `PropertyDecl` for non-sensitive tenant config (base URLs, region codes). Distinct from `secrets[]`. |
+
+`defineCLI()` cross-validates every `secretKeys` and `propertyKeys` reference against the CLI-level declarations. Mismatches throw `AkaiSpecError` at module load — no silent failures.
+
+### Tool keys
+
+Tool keys are **kebab-case**, optionally dot-namespaced for grouping:
+
+```
+chat-post-message
+users.me
+tickets.search-by-query
+activations.contract-benefit.mark-enrolled-ahead-of-ingest
+```
+
+Each dot-separated segment matches `[a-zA-Z][a-zA-Z0-9_]*(-[a-zA-Z0-9_]+)*` — first char a letter, hyphens must be followed by at least one word char (so `--`, leading/trailing `-`, and empty segments reject). Wire ids are `<cliId>.<toolKey>`.
+
+Underscores and camelCase are still accepted so existing tools keep working, but new tools should be kebab to match the convention in the [`akai-cli-tools`](https://github.com/akai-workflow-builder/akai-cli-tools) repo.
+
+### The `ctx` contract
+
+Tool handlers receive a frozen `ctx` with exactly six members:
+
+```ts
+interface ToolCtx<S extends string, P extends string> {
+  fetch:      (url: string, init?: RequestInit) => Promise<Response>;
+  secrets:    Readonly<Record<S, string | undefined>>;
+  properties: Readonly<Record<P, string | undefined>>;
+  logger:     ToolLogger;
+  signal:     AbortSignal;
+  workdir:    string;
+}
+```
+
+**What you get**
+
+- `fetch` — sandboxed `fetch` bound to the tool's egress allowlist.
+- `secrets` — only the secret keys the tool declared in `secretKeys`. Other workspace secrets are inaccessible.
+- `properties` — only the property keys the tool declared in `propertyKeys`. Non-sensitive tenant config (base URL, region) lives here, not in `secrets`.
+- `logger` — structured logger; writes to stderr. stdout is reserved for the tool's result.
+- `signal` — request `AbortSignal`. Forward it to `ctx.fetch` for cancellation and timeouts.
+- `workdir` — writable scratch directory scoped to this invocation.
+
+**What `ctx` deliberately omits**
+
+- No `process.env` accessor — secrets flow through `ctx.secrets` so the runtime can scope and audit them.
+- No `fs`, `child_process`, or `worker_threads` handles — `ctx` doesn't pre-wire them. The SDK does not sandbox the Node runtime; if a handler imports those modules directly, the host is responsible for restricting that out of band.
+- No handle to invoke sibling tools — composition is the planner's job.
+
+### Secrets — declarations vs references
+
+Secrets are declared once at the CLI level and referenced by key on each tool that needs them:
+
+```ts
+defineCLI({
+  secrets: [
+    { key: 'ZENDESK_API_TOKEN', name: 'API token', description: '...', required: true },
+  ],
+  tools: {
+    getTicket: tool({
+      options: {
+        secretKeys: ['ZENDESK_API_TOKEN'],
+        /* ... */
+      },
+      /* ... */
+    }),
+  },
+});
+```
+
+| | Field | Type | Role |
+|---|---|---|---|
+| CLI     | `secrets`            | `SecretDecl[]`                     | Operator-facing declarations |
+| Tool    | `options.secretKeys` | `string[]`                         | Per-tool subset |
+| Runtime | `ctx.secrets`        | `Readonly<Record<S, string \| undefined>>` | What the handler reads |
+
+When building `ctx`, the runtime walks the tool's declared `secretKeys`. Each key must be declared in the CLI's `secrets[]`; an undeclared reference throws `AkaiSpecError` at module load. At invocation, a `required: true` secret with no value throws `AkaiSecretError`. Optional secrets that the caller didn't supply appear on `ctx.secrets` as `undefined` so handlers can branch.
+
+`ctx.secrets[K]` is typed `string | undefined` for all `K` — optional secrets may be absent, so handlers narrow before use. Even when `required: true`, the SDK can't statically prove the runtime body shipped the value, so the type stays union.
+
+### Properties — non-sensitive tenant config
+
+Tenant-specific values that aren't credentials live in `properties[]`, not `secrets[]`. Examples: a workspace subdomain, a self-hosted base URL, a region code. The host runtime stores these without the encryption-at-rest treatment applied to secrets and may surface them in admin UIs unmasked.
+
+```ts
+defineCLI({
+  secrets:    [{ key: 'JIRA_API_TOKEN', name: 'API token',     description: '...', required: true }],
+  properties: [{ key: 'JIRA_BASE_URL',  name: 'Workspace URL', description: '...', required: true }],
+  tools: {
+    getIssue: tool({
+      options: {
+        secretKeys:   ['JIRA_API_TOKEN'],
+        propertyKeys: ['JIRA_BASE_URL'],
+        network:      { egress: { from: 'property:JIRA_BASE_URL' } },
+        isReadonly:   true,
+      },
+      handler: async ({ ctx }) => {
+        const base = ctx.properties.JIRA_BASE_URL!;
+        const tok  = ctx.secrets.JIRA_API_TOKEN!;
+        return ctx.fetch(`https://${base}/rest/api/3/issue/...`, {
+          headers: { Authorization: `Bearer ${tok}` },
+        });
+      },
+      /* ... */
+    }),
+  },
+});
+```
+
+| | Field | Type | Role |
+|---|---|---|---|
+| CLI     | `properties`            | `PropertyDecl[]`                    | Operator-facing declarations |
+| Tool    | `options.propertyKeys`  | `string[]`                          | Per-tool subset |
+| Runtime | `ctx.properties`        | `Readonly<Record<P, string \| undefined>>` | What the handler reads |
+
+`AkaiPropertyError` is thrown when a `required: true` property is missing at invocation time. Same lifecycle as `AkaiSecretError`, distinct class because the failure source is conceptually different.
+
+### Dynamic egress (multi-tenant connectors)
+
+For connectors where the host varies per tenant (Jira Cloud, Zendesk, Looker self-hosted, GHES, Salesforce), declare the host as a property and reference it from `egress`:
+
+```ts
+options: {
+  propertyKeys: ['JIRA_BASE_URL'],
+  network:      { egress: { from: 'property:JIRA_BASE_URL' } },
+}
+```
+
+`defineCLI()` cross-checks that the referenced key is declared in `properties[]` AND included in the tool's `propertyKeys`. The host runtime resolves the reference per invocation; SDK-side `buildCtx` throws `AkaiSpecError` to enforce that the host has resolved the egress before constructing `ctx`.
+
+### Egress allowlist
+
+Every tool declares its allowed outbound hosts:
+
+```ts
+options: {
+  network: { egress: 'api.example.com' },                  // single host (shorthand)
+  // or:    { egress: ['api.example.com', 'cdn.example.com'] },
+}
+```
+
+`ctx.fetch` enforces, in order:
+
+- **Protocol** — HTTPS-only in production. HTTP allowed only when `NODE_ENV === 'development'`.
+- **Host** — exact-or-suffix-with-dot. `api.example.com` matches itself and `*.api.example.com`; `evil.api.example.com.attacker.tld` does not.
+- **DNS preflight** — hostname resolved before the request. In production, addresses in private (RFC 1918), loopback, link-local, or unique-local IPv6 ranges are refused (IPv4, IPv6, v4-mapped, and canonicalized forms). In development the private-IP refusal is skipped so handlers can target local services.
+- **Redirects** — `redirect: 'error'` is pinned on every request, non-overridable. If the target responds with a 3xx, `fetch` itself rejects; the SDK never follows redirects, so a `Location:` to a public host cannot smuggle the request past the egress check.
+- **Identity headers** — `user-agent`, `x-akai-cli`, `x-akai-tool`, `x-akai-request-id` are stamped on every request. `x-akai-tenant` is stamped only when the host runtime passes a tenant id to `buildCtx`; otherwise it is removed even if a handler tried to set it. Handler-supplied values for any of these are always overwritten.
+
+Protocol, host, and DNS-preflight failures reject with `AkaiEgressError` before any network request is made. Redirect failures surface as a `fetch` rejection after the initial response — same outcome (no follow-through), different error type.
+
+Spec validation also rejects egress hosts that don't pass a syntactic DNS-hostname check — `localhost` (single label), IP literals, hosts with spaces or slashes — so they can't be declared in the first place. The check is shape-only; it doesn't verify the name is publicly resolvable, so internal DNS zones still pass the spec and are then handled at DNS-preflight time.
+
+### `isReadonly`
+
+Every tool must declare whether it mutates remote state:
+
+```ts
+options: {
+  isReadonly: true,   // reads, queries — no approval gate
+  // isReadonly: false, // writes — runtime pauses for human approval
+}
+```
+
+Two roles:
+
+1. **Planner hint** — exposed in the tool listing so plan UIs render write steps distinctly.
+2. **Runtime gate** — write tools cannot execute unless a confirmation flag is set, which the runtime flips only after the approval flow returns approved.
+
+No default. The SDK throws on omission — silent defaults would risk marking writes as readonly. **When in doubt, choose `false`** — false-positives cost one approval click; false-negatives cause silent mutation.
+
+### Output mode: JSON vs text
+
+Each handler receives an `isJson: boolean` flag. The caller chooses `format=json` or `format=text`; the handler returns either shape:
+
+```ts
+handler: async ({ input, ctx, isJson }) => {
+  const body = await fetchTheThing(/* ... */);
+  return isJson ? body : `Thing #${body.id} (${body.status})`;
+}
+```
+
+When `jsonOutput` is declared, the handler return type is `string | ZInfer<jsonOutput>`. When `jsonOutput` is omitted, the handler always returns a string.
+
+---
+
+## Worked example: Zendesk
+
+The repository's `examples/zendesk/` folder ships a five-tool, read-only Zendesk Support connector (not bundled in the published package):
+
+| Tool | Endpoint | Demonstrates |
+|---|---|---|
+| `users.me`       | `GET /users/me`        | Auth probe; simplest tool |
+| `users.get`      | `GET /users/{id}`      | Path parameter |
+| `tickets.get`    | `GET /tickets/{id}`    | Path parameter, 404 mapped to typed error |
+| `tickets.list`   | `GET /tickets`         | Cursor pagination |
+| `tickets.search` | `GET /search`          | Query composition, 422 surfaced |
+
+Each tool branches on `isJson` and uses the structured logger. The folder includes a smoke runner that mirrors the runtime's per-invocation dispatch (registry → `buildCtx()` → handler) so you can hit a real workspace from your terminal.
+
+---
+
+## Errors
+
+| Class | When |
+|---|---|
+| `AkaiSpecError`    | Invalid `tool()` / `defineCLI()` spec — thrown at module load |
+| `AkaiInputError`   | Tool input fails the declared zod schema — thrown by the runtime when validating the request body |
+| `AkaiSecretError`  | A `required: true` secret is missing at invocation time — thrown by `buildCtx` |
+| `AkaiPropertyError`| A `required: true` property is missing at invocation time — thrown by `buildCtx` |
+| `AkaiEgressError`  | `ctx.fetch` rejected the target |
+
+Every error extends `AkaiError`; the runtime maps each to a structured error envelope.
+
+---
+
+## Troubleshooting
+
+**`Cannot find name 'Response'`** — `tsconfig.json` is missing web-platform types. Add `"DOM"` to your existing `lib` entries (e.g. `"lib": ["ES2023", "DOM"]`) — setting `lib` overrides the target's defaults, so include both — or use `@types/node@^18+`.
+
+**`AkaiSpecError: undeclared secret 'X'`** — a `secretKeys` entry references a key that isn't in `defineCLI({ secrets: [...] })`.
+
+**`AkaiSpecError: undeclared property 'X'`** — a `propertyKeys` entry references a key that isn't in `defineCLI({ properties: [...] })`.
+
+**`AkaiSpecError: invalid id "..."`** — CLI `id` must be a lowercase slug matching `^[a-z][a-z0-9_-]*$`. The display label lives in `name`.
+
+**`AkaiSpecError: invalid egress host` for `localhost` / `127.0.0.1`** — `tool()` rejects IP literals and single-label hostnames (including `localhost`) at spec time, before `ctx.fetch` ever runs. For local development, use a tunnel (ngrok, Cloudflare Tunnel) that resolves to a public hostname.
+
+**`AkaiEgressError` against an unallowed host** — runtime egress check failed. Add the host to `options.network.egress` (matched exact-or-suffix-with-dot).
+
+**Type error: handler return doesn't match `jsonOutput`** — when `jsonOutput` is declared, the handler return type is `string | <structured shape>`. Branch on `isJson`.
+
+---
+
+## License
+
+TBD — license will be selected before the first public release.

package/bin/akai.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Tiny shim: keep the shebang here (TS sources can't carry it) and forward
+// to the compiled run(). Kept as JS so no build step has to prepend the
+// shebang to dist/.
+import { run } from '../dist/cli.js';
+
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    // Defensive — run() catches its own errors and returns an exit code,
+    // so this should never fire. Surface anything that slips through.
+    process.stderr.write(`akai: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+  },
+);

package/dist/cli.d.ts

@@ -0,0 +1,46 @@
+import type { CLIDef } from './types.js';
+type ParsedArgs = {
+    ok: true;
+    packagePath: string;
+    out: string | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse argv (minus `node` + script path). Single-command CLI today —
+ * `build-manifest` is the only verb. Exits non-zero with a clear stderr
+ * message on any usage error.
+ */
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+/**
+ * Resolve a package directory to its compiled entry, dynamic-import it,
+ * and verify the default export is a {@link CLIDef}. Reads `package.json`
+ * for `main`; falls back to `index.js`. Brand-checks `__akaiCLI: true` to
+ * reject hand-crafted objects that happen to share the shape.
+ */
+export declare function loadCli(packagePath: string): Promise<CLIDef>;
+/**
+ * Load the CLI, project it to a manifest, and write the JSON either to
+ * stdout (default) or the path given by `--out`.
+ *
+ * Uses `cli.toSchema()` (the instance method attached at `defineCLI`
+ * time) rather than this SDK's imported `toSchema(cli)`, so the target
+ * package's bundled SDK version wins. Per-tenant CLIs may ship with a
+ * different `@akai/cli` than the one running the binary — calling the
+ * instance method emits the manifest shape that package was authored
+ * against.
+ */
+export declare function buildManifest(packagePath: string, out: string | undefined): Promise<void>;
+/**
+ * Entry point used by the `bin/akai.js` shim. Returns the exit code so
+ * tests can assert on it without spawning a child process.
+ *
+ * Exit codes:
+ *   0 — success
+ *   1 — runtime error (missing/malformed package, import failure)
+ *   2 — usage error (bad/missing argv)
+ */
+export declare function run(argv: readonly string[]): Promise<number>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAiBzC,KAAK,UAAU,GACX;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAC1D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAyB7D;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgDlE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;GAQG;AACH,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAclE"}

package/dist/cli.js

@@ -0,0 +1,148 @@
+import { resolve, join, isAbsolute } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+function isFileNotFound(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'code' in err &&
+        err.code === 'ENOENT');
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+const USAGE = 'usage: akai build-manifest <package-path> [--out file]';
+/**
+ * Parse argv (minus `node` + script path). Single-command CLI today —
+ * `build-manifest` is the only verb. Exits non-zero with a clear stderr
+ * message on any usage error.
+ */
+export function parseArgs(argv) {
+    if (argv.length === 0)
+        return { ok: false, error: USAGE };
+    const [command, ...rest] = argv;
+    if (command === '-h' || command === '--help')
+        return { ok: false, error: USAGE };
+    if (command !== 'build-manifest')
+        return { ok: false, error: `unknown command: ${command}\n${USAGE}` };
+    let packagePath;
+    let out;
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '--out') {
+            const value = rest[i + 1];
+            if (value === undefined)
+                return { ok: false, error: '--out requires a filename' };
+            out = value;
+            i++;
+        }
+        else if (arg === '-h' || arg === '--help') {
+            return { ok: false, error: USAGE };
+        }
+        else if (packagePath === undefined) {
+            packagePath = arg;
+        }
+        else {
+            return { ok: false, error: `unexpected argument: ${arg}` };
+        }
+    }
+    if (packagePath === undefined)
+        return { ok: false, error: `missing <package-path>\n${USAGE}` };
+    return { ok: true, packagePath, out };
+}
+/**
+ * Resolve a package directory to its compiled entry, dynamic-import it,
+ * and verify the default export is a {@link CLIDef}. Reads `package.json`
+ * for `main`; falls back to `index.js`. Brand-checks `__akaiCLI: true` to
+ * reject hand-crafted objects that happen to share the shape.
+ */
+export async function loadCli(packagePath) {
+    const abs = isAbsolute(packagePath) ? packagePath : resolve(process.cwd(), packagePath);
+    const pkgJsonPath = join(abs, 'package.json');
+    let entry = join(abs, 'index.js');
+    // ENOENT is the only "fall through to the default" case. Anything else
+    // (permission denied, malformed JSON, missing/invalid `main`) is a hard
+    // error — silently emitting a manifest from the wrong entry point is worse
+    // than failing loud.
+    let pkgRaw;
+    try {
+        pkgRaw = await readFile(pkgJsonPath, 'utf8');
+    }
+    catch (err) {
+        if (!isFileNotFound(err)) {
+            throw new Error(`${packagePath}: failed to read package.json: ${errorMessage(err)}`);
+        }
+    }
+    if (pkgRaw !== undefined) {
+        let main;
+        try {
+            main = JSON.parse(pkgRaw).main;
+        }
+        catch (err) {
+            throw new Error(`${packagePath}/package.json: invalid JSON: ${errorMessage(err)}`);
+        }
+        if (typeof main === 'string' && main.length > 0) {
+            entry = join(abs, main);
+        }
+    }
+    let mod;
+    try {
+        mod = await import(pathToFileURL(entry).href);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`failed to import ${entry}: ${msg}`);
+    }
+    const def = mod.default;
+    if (def === null ||
+        typeof def !== 'object' ||
+        def.__akaiCLI !== true) {
+        throw new Error(`${packagePath}: default export is not a CLIDef (missing __akaiCLI brand)`);
+    }
+    return def;
+}
+/**
+ * Load the CLI, project it to a manifest, and write the JSON either to
+ * stdout (default) or the path given by `--out`.
+ *
+ * Uses `cli.toSchema()` (the instance method attached at `defineCLI`
+ * time) rather than this SDK's imported `toSchema(cli)`, so the target
+ * package's bundled SDK version wins. Per-tenant CLIs may ship with a
+ * different `@akai/cli` than the one running the binary — calling the
+ * instance method emits the manifest shape that package was authored
+ * against.
+ */
+export async function buildManifest(packagePath, out) {
+    const cli = await loadCli(packagePath);
+    const json = `${JSON.stringify(cli.toSchema(), null, 2)}\n`;
+    if (out !== undefined) {
+        await writeFile(out, json, 'utf8');
+    }
+    else {
+        process.stdout.write(json);
+    }
+}
+/**
+ * Entry point used by the `bin/akai.js` shim. Returns the exit code so
+ * tests can assert on it without spawning a child process.
+ *
+ * Exit codes:
+ *   0 — success
+ *   1 — runtime error (missing/malformed package, import failure)
+ *   2 — usage error (bad/missing argv)
+ */
+export async function run(argv) {
+    const parsed = parseArgs(argv);
+    if (!parsed.ok) {
+        process.stderr.write(`akai: ${parsed.error}\n`);
+        return 2;
+    }
+    try {
+        await buildManifest(parsed.packagePath, parsed.out);
+        return 0;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`akai build-manifest: ${msg}\n`);
+        return 1;
+    }
+}

package/dist/ctx/build-ctx.d.ts

@@ -0,0 +1,46 @@
+import { type PropertyValues, type SecretValues } from './secrets.js';
+import type { CLIDef, ToolCtx, ToolLogger } from '../types.js';
+/**
+ * Inputs to {@link buildCtx} — what the host runtime collects per
+ * invocation before calling a tool's handler.
+ */
+export interface BuildCtxParams {
+    readonly cli: CLIDef;
+    readonly toolName: string;
+    /** Resolved secret values (one per key declared at the CLI level), sourced from the runtime request body. */
+    readonly secretValues: SecretValues;
+    /** Resolved tenant-property values, sourced alongside `secretValues`. Optional — defaults to `{}`. */
+    readonly propertyValues?: PropertyValues;
+    readonly logger: ToolLogger;
+    readonly signal: AbortSignal;
+    readonly workdir: string;
+    readonly sdkVersion: string;
+    readonly tenantId?: string;
+    /**
+     * Extra roots beyond `workdir` + `os.tmpdir()` that the runtime considers
+     * safe for this tool's path I/O. Worker passes its `AGENT_WORKDIR` and
+     * `DT_SAFE_PATH_ROOTS` here for parity with the rest of its CLI tree.
+     */
+    readonly extraSafePathRoots?: readonly string[];
+}
+/**
+ * Assemble a frozen {@link ToolCtx} for one tool invocation: resolves
+ * the named tool from the CLI, scopes secrets to the keys the tool
+ * declared, and wires a sandboxed `ctx.fetch` bound to the tool's
+ * egress allowlist (or a throwing stub when the tool is native).
+ *
+ * Used by the host runtime per `/tools/execute` request — handler
+ * authors receive the resulting `ctx` and don't call `buildCtx`
+ * directly.
+ *
+ * @param params - see {@link BuildCtxParams}.
+ * @returns frozen {@link ToolCtx} ready to hand to the tool's handler.
+ * @throws {Error} when `toolName` is not registered in `cli.tools`.
+ * @throws {AkaiSecretError} when the resolved tool's `secretKeys`
+ *   reference a key not declared at the CLI level, or when a referenced
+ *   key whose CLI declaration is `required: true` has no value in
+ *   `secretValues`. CLI-level required secrets that this tool does not
+ *   reference are not checked.
+ */
+export declare function buildCtx(params: BuildCtxParams): ToolCtx;
+//# sourceMappingURL=build-ctx.d.ts.map

package/dist/ctx/build-ctx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-ctx.d.ts","sourceRoot":"","sources":["../../src/ctx/build-ctx.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAc,MAAM,EAAiB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG1F;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6GAA6G;IAC7G,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,sGAAsG;IACtG,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AA4CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CA4CxD"}