{"_id":"@agenomics/action-runtime","name":"@agenomics/action-runtime","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agenomics/action-runtime","version":"0.1.0","description":"AEP action-definition runtime: Result type, ok/err constructors, wrap helper, and the defineAction builder used by AEP capabilities.","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"keywords":["agenomics","aep","action-runtime","result-type","capabilities"],"repository":{"type":"git","url":"git+https://github.com/agenomics-labs/protocol.git","directory":"sdk/action-runtime"},"bugs":{"url":"https://github.com/agenomics-labs/protocol/issues"},"homepage":"https://github.com/agenomics-labs/protocol/tree/main/sdk/action-runtime#readme","license":"Apache-2.0","private":false,"publishConfig":{"access":"public"},"scripts":{"build":"tsc","prepublishOnly":"tsc","test":"node --import tsx --test test/*.test.ts"},"devDependencies":{"@types/node":"^24.12.4","tsx":"^4.0.0","typescript":"^6.0.3"},"gitHead":"946789848d7d388c4688010e7537a2b9b5e7d4c5","_id":"@agenomics/action-runtime@0.1.0","_nodeVersion":"24.18.0","_npmVersion":"11.18.0","dist":{"integrity":"sha512-N2NLBr3r6nXV8XpB+Uz7TSXmQNmWI1RrDxbvwLwyIyyOVasiaiz5vERSxZO7rh/Wsj8cetCMu68hIDK5XSFbkg==","shasum":"7f79f98800d4cac6905333d35837af2e18027970","tarball":"https://registry.npmjs.org/@agenomics/action-runtime/-/action-runtime-0.1.0.tgz","fileCount":7,"unpackedSize":21397,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQClwG2mb+nSE6Px0S4jUoCB3nD9KUzTcKUfsSDxYDqXPgIhANT/VCnw5xjSrBL1xOlsD43Xo/iDMwITHzC250H2tAtd"}]},"_npmUser":{"name":"k2jac9","email":"alexcastellanos29@gmail.com"},"directories":{},"maintainers":[{"name":"k2jac9","email":"alexcastellanos29@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/action-runtime_0.1.0_1784609927532_0.5846360289167529"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-21T04:58:47.401Z","0.1.0":"2026-07-21T04:58:47.663Z","modified":"2026-07-21T04:58:47.858Z"},"maintainers":[{"name":"k2jac9","email":"alexcastellanos29@gmail.com"}],"description":"AEP action-definition runtime: Result type, ok/err constructors, wrap helper, and the defineAction builder used by AEP capabilities.","homepage":"https://github.com/agenomics-labs/protocol/tree/main/sdk/action-runtime#readme","keywords":["agenomics","aep","action-runtime","result-type","capabilities"],"repository":{"type":"git","url":"git+https://github.com/agenomics-labs/protocol.git","directory":"sdk/action-runtime"},"bugs":{"url":"https://github.com/agenomics-labs/protocol/issues"},"license":"Apache-2.0","readme":"# @agenomics/action-runtime\n\nA tiny `Result` type and `defineAction` builder for AEP capability handlers.\n\nThe runtime contract for capabilities advertised in an AEP capability\nmanifest (ADR-060). Provides a typed `Result<T, E>` discriminated union\nwith `ok` / `err` constructors, a `wrap` helper that converts any\n`Promise`-returning function into a `Result`-returning one (so\nexceptions never escape the action boundary), and a `defineAction`\nbuilder that takes a plain async handler and produces an `Action` with\na uniform `run(input)` shape. Zero runtime dependencies — drop it into\nany AEP capability without pulling Solana code into the action surface.\n\n## Install\n\n```sh\nnpm install @agenomics/action-runtime\n```\n\n_Not yet on npm; pre-publish 0.1.0. See `docs/SDK_PUBLISH.md` for the publish path._\n\n## Quick example\n\n```ts\nimport { defineAction, ok, err } from \"@agenomics/action-runtime\";\nimport type { Result } from \"@agenomics/action-runtime\";\n\nconst addAction = defineAction({\n  name: \"add\",\n  description: \"Adds two numbers\",\n  handler: async (input: { a: number; b: number }) => input.a + input.b,\n});\n\nconst result: Result<number, Error> = await addAction.run({ a: 3, b: 4 });\nif (result.ok) {\n  console.log(\"sum:\", result.value); // sum: 7\n} else {\n  console.error(\"failed:\", result.error.message);\n}\n\n// Manual constructors when you don't need a wrapped handler:\nconst success: Result<string> = ok(\"done\");\nconst failure: Result<never, Error> = err(new Error(\"nope\"));\n```\n\n## Key exports\n\n- `Result<T, E = Error>` — discriminated union: `{ ok: true; value: T } | { ok: false; error: E }`. Narrows cleanly via `result.ok`.\n- `ok(value)` / `err(error)` — single-line constructors for the two variants.\n- `wrap(fn)` — runs a `() => Promise<T>`, captures any throw, and returns `Promise<Result<T, ActionError>>`. The thrown value is **never** returned verbatim: it is converted to a redacted `ActionError` (see Security boundary).\n- `ActionSpec<TInput, TOutput>` — `{ name, description, validate?, handler }`.\n- `Action<TInput, TOutput>` — `{ name, description, run: (input: unknown) => Promise<Result<TOutput, Error>> }`.\n- `defineAction(spec)` — builds an `Action` from a spec. The handler is wrapped with `wrap`, so `run` never throws.\n- `ActionError` — `extends Error`, adds a stable machine `code`. The only error type that ever crosses the action boundary back to a caller.\n- `ValidationError` — throw from `validate` for invalid input; surfaces as `ActionError` with `code: \"VALIDATION_ERROR\"`.\n- `setInternalErrorSink(fn)` — register a trusted server-side logger that receives the **raw, unredacted** error. Never wire this anywhere reachable by an untrusted caller.\n\n## Security boundary (SDK-F3 — cycle-4 audit)\n\n`defineAction` is a capability runtime, not a validator. Two contracts are\nnow explicit:\n\n1. **No implicit input validation.** Without a `validate` hook the handler\n   receives whatever the (possibly untrusted) caller passed — `TInput` is\n   erased at runtime. For any handler that moves funds or touches signing\n   material, supply `validate`; it runs *before* `handler` and must `throw`\n   (e.g. `ValidationError`) on bad input.\n\n2. **Error redaction.** RPC URLs, filesystem (keypair) paths, and\n   key/secret-shaped blobs are stripped from the `error.message` returned\n   to callers; the message is length-bounded; the raw `Error`/`.stack` is\n   never returned; non-`Error` throws are reduced to a type tag (no value\n   leak). The unredacted error is delivered only to `setInternalErrorSink`\n   if one is registered.\n\n## Related packages\n\n- `@agenomics/client` — call on-chain reads (e.g. `fetchProfile`, `fetchVault`) inside an action handler; throws inside the handler become typed `err` results.\n- `@agenomics/idl` — pull cluster-keyed program IDs into the same handler when you need to dispatch by network.\n- `@agenomics/capability-manifest-validator` — declare each `defineAction` you ship in your published manifest's `capabilities[]` array; the validator confirms the manifest matches the on-chain commitment.\n- `@agenomics/sas-resolver` — fetch reputation context for the requesting agent before running the action handler.\n\n## Status\n\n0.1.0 — pre-publish; private until license + READMEs land per `docs/SDK_PUBLISH.md`.\n","readmeFilename":"README.md","_rev":"1-4842709abb0392e09bafe06ed25fcd6b"}