@akai-workflow-builder/cli-sdk 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `@akai-workflow-builder/cli-sdk` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.3]
+
+### Added
+
+- `AkaiToolError` — a typed, caller-facing tool failure carrying a stable `kind`
+  (`not_found` | `forbidden` | `auth_expired` | `invalid_input` | `conflict` |
+  `rate_limited` | `unavailable`), `message`, and optional `meta`. Pins
+  `name` to `'AkaiToolError'` so the host runtime can brand-check the
+  serialized shape (`{ name, kind, message, meta? }`) with no SDK dependency,
+  map `kind` to an HTTP status, and surface the message verbatim.
+- Ergonomic static factories on `AkaiToolError`: `notFound`, `forbidden`,
+  `authExpired`, `invalidInput`, `conflict`, `rateLimited`, `unavailable`.
+- Exported the `ToolErrorKind` type from the package entrypoint.

package/README.md

@@ -346,9 +346,36 @@ Each tool branches on `isJson` and uses the structured logger. The folder includ
 | `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 |
+| `AkaiToolError`    | A handler threw a typed, caller-facing failure — the host maps `kind` to an HTTP status and surfaces the message verbatim |
 
 Every error extends `AkaiError`; the runtime maps each to a structured error envelope.
 
+### Typed tool errors
+
+Throw `AkaiToolError` from a handler to give an expected failure a stable classification and author-vetted wording. The host runtime brand-checks the thrown value by its serialized shape — `{ name: 'AkaiToolError', kind, message, meta? }` — with no SDK dependency, maps `kind` to an HTTP status, and returns `message` to the caller **verbatim**. Keep messages secret-free.
+
+```ts
+import { AkaiToolError } from '@akai-workflow-builder/cli-sdk';
+
+const res = await ctx.fetch(`https://api.example.com/tickets/${id}`);
+if (res.status === 404) throw AkaiToolError.notFound(`No ticket ${id}`, { id });
+if (res.status === 429) throw AkaiToolError.rateLimited('Slow down', { retryAfterMs: 1000 });
+```
+
+Factories — each sets the matching `kind`:
+
+| Factory | `kind` | Host status |
+|---|---|---|
+| `AkaiToolError.notFound(msg, meta?)`     | `not_found`     | 404 |
+| `AkaiToolError.forbidden(msg, meta?)`    | `forbidden`     | 403 |
+| `AkaiToolError.authExpired(msg, meta?)`  | `auth_expired`  | 401 |
+| `AkaiToolError.invalidInput(msg, meta?)` | `invalid_input` | 422 |
+| `AkaiToolError.conflict(msg, meta?)`     | `conflict`      | 409 |
+| `AkaiToolError.rateLimited(msg, meta?)`  | `rate_limited`  | 429 (retryable) |
+| `AkaiToolError.unavailable(msg, meta?)`  | `unavailable`   | 503 (retryable) |
+
+Untyped throws are classified generically (a 500 with a derived message).
+
 ---
 
 ## Troubleshooting

package/dist/errors.d.ts

@@ -25,4 +25,60 @@ export declare class AkaiPropertyError extends AkaiError {
 /** `ctx.safePath` rejected a path that resolves outside the allowed roots. */
 export declare class AkaiPathError extends AkaiError {
 }
+/**
+ * Stable, vendor-neutral classification for a caller-facing tool failure.
+ *
+ * The host runtime maps each `kind` to an HTTP status and surfaces the
+ * accompanying `message` to the caller verbatim, so an agent can reason about
+ * the failure programmatically (fix the id, ask to be granted access,
+ * reconnect, retry) instead of seeing an opaque 500.
+ *
+ * - `not_found` — host maps to **404**: the entity does not exist or is not
+ *   visible to this caller. Check the id/URL and that you have access.
+ * - `forbidden` — host maps to **403**: the entity exists but the caller lacks
+ *   permission (not shared, insufficient scope).
+ * - `auth_expired` — host maps to **401**: the credential is invalid or expired;
+ *   reconnect the integration.
+ * - `invalid_input` — host maps to **422**: arguments are well-formed but violate
+ *   a runtime constraint the schema cannot express.
+ * - `conflict` — host maps to **409**: the request conflicts with current state
+ *   (already exists, version mismatch).
+ * - `rate_limited` — host maps to **429**: an upstream throttle was hit; retryable.
+ *   Put a hint in `meta` (e.g. `{ retryAfterMs }`).
+ * - `unavailable` — host maps to **503**: upstream is down, timed out, or
+ *   unreachable; retryable.
+ */
+export type ToolErrorKind = 'not_found' | 'forbidden' | 'auth_expired' | 'invalid_input' | 'conflict' | 'rate_limited' | 'unavailable';
+/**
+ * Caller-facing tool failure with a stable, vendor-neutral {@link ToolErrorKind}.
+ *
+ * Throw this from a tool handler when you want bespoke, author-vetted wording
+ * for an expected failure. The host runtime brand-checks the thrown value by its
+ * serialized shape — `{ name: 'AkaiToolError', kind, message, meta? }` — so the
+ * `name` is pinned to `'AkaiToolError'` in the constructor and survives across
+ * package-boundary `instanceof` gaps. On a match the host maps `kind` to an HTTP
+ * status and returns `message` to the caller **verbatim**, so the message must be
+ * secret-free and safe to expose. Untyped throws are classified generically.
+ *
+ * @example
+ * throw AkaiToolError.notFound(`No ticket ${id}`, { id });
+ */
+export declare class AkaiToolError extends AkaiError {
+    readonly kind: ToolErrorKind;
+    constructor(kind: ToolErrorKind, message: string, meta?: Record<string, unknown>);
+    /** `invalid_input` → host **422**: args violate a runtime constraint the schema can't express. */
+    static invalidInput(message: string, meta?: Record<string, unknown>): AkaiToolError;
+    /** `not_found` → host **404**: the entity doesn't exist or isn't visible to this caller. */
+    static notFound(message: string, meta?: Record<string, unknown>): AkaiToolError;
+    /** `forbidden` → host **403**: the entity exists but the caller lacks permission. */
+    static forbidden(message: string, meta?: Record<string, unknown>): AkaiToolError;
+    /** `auth_expired` → host **401**: the credential is invalid or expired; reconnect. */
+    static authExpired(message: string, meta?: Record<string, unknown>): AkaiToolError;
+    /** `conflict` → host **409**: the request conflicts with current state. */
+    static conflict(message: string, meta?: Record<string, unknown>): AkaiToolError;
+    /** `rate_limited` → host **429**: upstream throttle hit; retryable (e.g. `meta.retryAfterMs`). */
+    static rateLimited(message: string, meta?: Record<string, unknown>): AkaiToolError;
+    /** `unavailable` → host **503**: upstream down/timed-out/unreachable; retryable. */
+    static unavailable(message: string, meta?: Record<string, unknown>): AkaiToolError;
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC5B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAK5D;AAED,2EAA2E;AAC3E,qBAAa,aAAc,SAAQ,SAAS;CAAG;AAE/C,+EAA+E;AAC/E,qBAAa,cAAe,SAAQ,SAAS;CAAG;AAEhD,8CAA8C;AAC9C,qBAAa,eAAgB,SAAQ,SAAS;CAAG;AAEjD,sDAAsD;AACtD,qBAAa,eAAgB,SAAQ,SAAS;CAAG;AAEjD,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,SAAS;CAAG;AAGnD,8EAA8E;AAC9E,qBAAa,aAAc,SAAQ,SAAS;CAAG"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC5B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAK5D;AAED,2EAA2E;AAC3E,qBAAa,aAAc,SAAQ,SAAS;CAAG;AAE/C,+EAA+E;AAC/E,qBAAa,cAAe,SAAQ,SAAS;CAAG;AAEhD,8CAA8C;AAC9C,qBAAa,eAAgB,SAAQ,SAAS;CAAG;AAEjD,sDAAsD;AACtD,qBAAa,eAAgB,SAAQ,SAAS;CAAG;AAEjD,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,SAAS;CAAG;AAGnD,8EAA8E;AAC9E,qBAAa,aAAc,SAAQ,SAAS;CAAG;AAE/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,WAAW,GACX,cAAc,GACd,eAAe,GACf,UAAU,GACV,cAAc,GACd,aAAa,CAAC;AAElB;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBACjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAMhF,kGAAkG;IAClG,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAInF,4FAA4F;IAC5F,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAI/E,qFAAqF;IACrF,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAIhF,sFAAsF;IACtF,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAIlF,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAI/E,kGAAkG;IAClG,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAIlF,oFAAoF;IACpF,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;CAGnF"}

package/dist/errors.js

@@ -29,3 +29,53 @@ export class AkaiPropertyError extends AkaiError {
 /** `ctx.safePath` rejected a path that resolves outside the allowed roots. */
 export class AkaiPathError extends AkaiError {
 }
+/**
+ * Caller-facing tool failure with a stable, vendor-neutral {@link ToolErrorKind}.
+ *
+ * Throw this from a tool handler when you want bespoke, author-vetted wording
+ * for an expected failure. The host runtime brand-checks the thrown value by its
+ * serialized shape — `{ name: 'AkaiToolError', kind, message, meta? }` — so the
+ * `name` is pinned to `'AkaiToolError'` in the constructor and survives across
+ * package-boundary `instanceof` gaps. On a match the host maps `kind` to an HTTP
+ * status and returns `message` to the caller **verbatim**, so the message must be
+ * secret-free and safe to expose. Untyped throws are classified generically.
+ *
+ * @example
+ * throw AkaiToolError.notFound(`No ticket ${id}`, { id });
+ */
+export class AkaiToolError extends AkaiError {
+    kind;
+    constructor(kind, message, meta) {
+        super(message, meta);
+        this.name = 'AkaiToolError';
+        this.kind = kind;
+    }
+    /** `invalid_input` → host **422**: args violate a runtime constraint the schema can't express. */
+    static invalidInput(message, meta) {
+        return new AkaiToolError('invalid_input', message, meta);
+    }
+    /** `not_found` → host **404**: the entity doesn't exist or isn't visible to this caller. */
+    static notFound(message, meta) {
+        return new AkaiToolError('not_found', message, meta);
+    }
+    /** `forbidden` → host **403**: the entity exists but the caller lacks permission. */
+    static forbidden(message, meta) {
+        return new AkaiToolError('forbidden', message, meta);
+    }
+    /** `auth_expired` → host **401**: the credential is invalid or expired; reconnect. */
+    static authExpired(message, meta) {
+        return new AkaiToolError('auth_expired', message, meta);
+    }
+    /** `conflict` → host **409**: the request conflicts with current state. */
+    static conflict(message, meta) {
+        return new AkaiToolError('conflict', message, meta);
+    }
+    /** `rate_limited` → host **429**: upstream throttle hit; retryable (e.g. `meta.retryAfterMs`). */
+    static rateLimited(message, meta) {
+        return new AkaiToolError('rate_limited', message, meta);
+    }
+    /** `unavailable` → host **503**: upstream down/timed-out/unreachable; retryable. */
+    static unavailable(message, meta) {
+        return new AkaiToolError('unavailable', message, meta);
+    }
+}

package/dist/index.d.ts

@@ -8,7 +8,8 @@ export type { BuildCtxParams } from './ctx/build-ctx.js';
 export type { AnyToolDef, CLIDef, CLISpec, DynamicEgress, InputOf, NetworkOptions, OutputOf, PropertiesOf, PropertyDecl, SecretDecl, SecretsOf, ToolCtx, ToolDef, ToolLogger, ToolOptions, ToolSpec, } from './types.js';
 export { createSafePath } from './ctx/safe-path.js';
 export type { SafePath } from './ctx/safe-path.js';
-export { AkaiEgressError, AkaiError, AkaiInputError, AkaiPathError, AkaiPropertyError, AkaiSecretError, AkaiSpecError, } from './errors.js';
+export { AkaiEgressError, AkaiError, AkaiInputError, AkaiPathError, AkaiPropertyError, AkaiSecretError, AkaiSpecError, AkaiToolError, } from './errors.js';
+export type { ToolErrorKind } from './errors.js';
 export { ConnectionManifestSchema, ManifestJSONSchema, SCHEMA_VERSION, toSchema, validateManifest, } from './manifest/index.js';
 export type { ConnectionManifest, DynamicEgressManifest, HttpToolManifest, ManifestProperty, ManifestSecret, NativeToolManifest, SchemaVersion, ToolManifest, } from './manifest/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EACV,UAAU,EACV,MAAM,EACN,OAAO,EACP,aAAa,EACb,OAAO,EACP,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,OAAO,EACP,OAAO,EACP,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EACV,UAAU,EACV,MAAM,EACN,OAAO,EACP,aAAa,EACb,OAAO,EACP,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,OAAO,EACP,OAAO,EACP,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -4,5 +4,5 @@ export { filePath, FILE_INPUT_META_KEY } from './file-input.js';
 export { buildScopedSecrets, buildScopedProperties } from './ctx/secrets.js';
 export { buildCtx } from './ctx/build-ctx.js';
 export { createSafePath } from './ctx/safe-path.js';
-export { AkaiEgressError, AkaiError, AkaiInputError, AkaiPathError, AkaiPropertyError, AkaiSecretError, AkaiSpecError, } from './errors.js';
+export { AkaiEgressError, AkaiError, AkaiInputError, AkaiPathError, AkaiPropertyError, AkaiSecretError, AkaiSpecError, AkaiToolError, } from './errors.js';
 export { ConnectionManifestSchema, ManifestJSONSchema, SCHEMA_VERSION, toSchema, validateManifest, } from './manifest/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akai-workflow-builder/cli-sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Authoring SDK for atomic, agent-executable CLIs and tools.",
   "keywords": [
     "akai",
@@ -28,6 +28,7 @@
   "files": [
     "bin",
     "dist",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],