@kana-ai/edgar-sdk 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +430 -2
  3. package/dist/src/build/cli.d.ts +6 -0
  4. package/dist/src/build/cli.js +110 -0
  5. package/dist/src/build/json.d.ts +2 -0
  6. package/dist/src/build/json.js +71 -0
  7. package/dist/src/build/manifest.d.ts +15 -0
  8. package/dist/src/build/manifest.js +111 -0
  9. package/dist/src/define/card-block.d.ts +15 -0
  10. package/dist/src/define/card-block.js +66 -0
  11. package/dist/src/define/context.d.ts +60 -0
  12. package/dist/src/define/context.js +1 -0
  13. package/dist/src/define/extension.d.ts +58 -0
  14. package/dist/src/define/extension.js +14 -0
  15. package/dist/src/define/hook.d.ts +61 -0
  16. package/dist/src/define/hook.js +72 -0
  17. package/dist/src/define/service.d.ts +32 -0
  18. package/dist/src/define/service.js +33 -0
  19. package/dist/src/define/tool.d.ts +93 -0
  20. package/dist/src/define/tool.js +24 -0
  21. package/dist/src/define/tracker.d.ts +59 -0
  22. package/dist/src/define/tracker.js +27 -0
  23. package/dist/src/index.d.ts +15 -0
  24. package/dist/src/index.js +12 -0
  25. package/dist/src/outcome/end.d.ts +61 -0
  26. package/dist/src/outcome/end.js +292 -0
  27. package/dist/src/outcome/failures.d.ts +15 -0
  28. package/dist/src/outcome/failures.js +57 -0
  29. package/dist/src/outcome/limits.d.ts +13 -0
  30. package/dist/src/outcome/limits.js +115 -0
  31. package/dist/src/outcome/outcome.d.ts +32 -0
  32. package/dist/src/outcome/outcome.js +59 -0
  33. package/dist/src/outcome/plain.d.ts +7 -0
  34. package/dist/src/outcome/plain.js +55 -0
  35. package/dist/src/outcome/result.d.ts +35 -0
  36. package/dist/src/outcome/result.js +58 -0
  37. package/dist/src/provider/child.d.ts +51 -0
  38. package/dist/src/provider/child.js +152 -0
  39. package/dist/src/provider/serve.d.ts +42 -0
  40. package/dist/src/provider/serve.js +175 -0
  41. package/dist/src/runtime/index.d.ts +4 -0
  42. package/dist/src/runtime/index.js +3 -0
  43. package/dist/src/runtime/invoke.d.ts +10 -0
  44. package/dist/src/runtime/invoke.js +232 -0
  45. package/dist/src/runtime/network.d.ts +20 -0
  46. package/dist/src/runtime/network.js +120 -0
  47. package/dist/src/runtime/ports.d.ts +31 -0
  48. package/dist/src/runtime/ports.js +1 -0
  49. package/dist/src/runtime/secrets.d.ts +13 -0
  50. package/dist/src/runtime/secrets.js +33 -0
  51. package/dist/src/testing/context.d.ts +12 -0
  52. package/dist/src/testing/context.js +39 -0
  53. package/dist/src/testing/index.d.ts +3 -0
  54. package/dist/src/testing/index.js +3 -0
  55. package/dist/src/testing/mock.d.ts +16 -0
  56. package/dist/src/testing/mock.js +39 -0
  57. package/dist/src/wire/codec.d.ts +46 -0
  58. package/dist/src/wire/codec.js +134 -0
  59. package/dist/src/wire/lines.d.ts +10 -0
  60. package/dist/src/wire/lines.js +41 -0
  61. package/package.json +48 -3
package/README.md CHANGED
@@ -1,3 +1,431 @@
1
- # Temporary Holding Version
1
+ # @kana-ai/edgar-sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The SDK defines an EDGAR extension in TypeScript, and builds the `edgar-extension.json` manifest that the engine reads. It also holds the parts that the extension runtime and the provider runtimes run on: the wire codec, the call invoker, the network policy and the provider server.
4
+
5
+ Use the SDK when you write an extension: a tool that a stage or a role calls, a tracker, a guardrail hook or an environment provider. For a whole extension from start to end, see the [`with-custom-extension`](/examples/with-custom-extension/README.md) case. For the messages between the engine and the runtime, see [`@kana-ai/edgar-contracts`](/packages/contracts/README.md).
6
+
7
+ ## Entry points
8
+
9
+ | Import | What it holds | Use it in |
10
+ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
11
+ | `@kana-ai/edgar-sdk` | `defineExtension`, `defineTool`, `disableTool`, `defineTracker`, the card block helpers, `defineEnvironment`, `defineHook`, `pass`, `deny`, `jsonSchema`, the outcome functions, the failure helpers, the `Result` helpers, and the types `Ctx`, `PortError`, `PortResult` | An extension's `src/index.ts` |
12
+ | `@kana-ai/edgar-sdk/result` | `Result`, `ok`, `err`, `attempt`, `attemptAsync`, `map`, `mapError`, `andThen`, `unwrapOr`, `all`, `expectOk` | Any module that returns a failure as a value |
13
+ | `@kana-ai/edgar-sdk/testing` | `testContext`, `mockOrigin` | An extension's unit tests |
14
+ | `@kana-ai/edgar-sdk/build` | `toManifest` | The build command; you do not need it in an extension |
15
+ | `@kana-ai/edgar-sdk/runtime` | `invoke`, `callables`, the network policy | The extension runtime, `apps/runtime` |
16
+ | `@kana-ai/edgar-sdk/codec` | The JSON-RPC line codec, `CONTRACT`, `errorCodes` | The runtimes |
17
+ | `@kana-ai/edgar-sdk/provider` | `serve`, `toolRequest`, `failedSession`, `skillList` | A provider runtime, `apps/provider-<name>` |
18
+ | `@kana-ai/edgar-sdk/child` | `spawnVendor`, `channel` | A provider runtime that drives a vendor's program |
19
+ | `edgar-extension-build <entry>` | The command that writes the manifest and the schemas | An extension's `build` script |
20
+
21
+ ## Define an extension
22
+
23
+ An extension is the default export of its entry module. This one has one tool, `count_lines`, which reads a file in the run's sandbox:
24
+
25
+ ```ts
26
+ import { z } from "zod";
27
+ import { defineExtension, defineTool, done, permanentFailure } from "@kana-ai/edgar-sdk";
28
+
29
+ export default defineExtension({
30
+ name: "notes",
31
+ capabilities: ["sandbox:read"],
32
+ tools: {
33
+ count_lines: defineTool({
34
+ description: "Count the lines of a file in the sandbox",
35
+ input: z.object({ path: z.string() }),
36
+ output: z.object({ lines: z.number() }),
37
+ capabilities: ["sandbox:read"],
38
+ execute: async ({ path }, ctx) => {
39
+ const file = await ctx.sandbox.read(path);
40
+ if (!file.ok) return permanentFailure("forbidden", file.error.message);
41
+ return done({ lines: file.value.split("\n").length });
42
+ },
43
+ }),
44
+ },
45
+ });
46
+ ```
47
+
48
+ A tool's full name is `<extension>__<tool>`, so a workflow calls this one as `notes__count_lines`.
49
+
50
+ ### `defineExtension(spec)`
51
+
52
+ | Key | What it declares |
53
+ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54
+ | `name` | The extension's name, as `[extensions] enabled` names it. The version comes from the package's `package.json`. |
55
+ | `capabilities` | Each capability that a tool or a hook of the extension may use. A tool can use only a capability that the extension also declares. |
56
+ | `secrets` | Each secret, with the hosts that a call that holds it may reach: `{ GITHUB_TOKEN: { hosts: ["api.github.com"] } }`. |
57
+ | `config` | The schema of the project's `[extensions.<name>]` table. |
58
+ | `tools` | The tools, by name. |
59
+ | `tracker` | A tracker, from `defineTracker`. Several enabled extensions may declare one: the project's trackers are those whose `[extensions.<name>.columns]` it maps. |
60
+ | `hooks` | Guardrail hooks, from `defineHook`, by name. |
61
+ | `environments` | Environment providers, from `defineEnvironment`, by name. |
62
+ | `webhooks` | Webhook routes. `edgar check` warns with `W023`: no webhook route exists yet. |
63
+ | `workflows`, `roles`, `skills` | The paths of the workflows, roles and skills that the extension ships to a project. |
64
+ | `executables` | The programs that the extension runs. `requires` lists each program that the machine must have on `PATH`, as `{ name, reason }`. `provides` lists each executable file that the package ships, as `{ name, path }`. See [Programs](#programs). |
65
+
66
+ ### Programs
67
+
68
+ An extension that runs a program declares it. `edgar check` then reports a missing program before a run starts, and `edgar extensions approve` shows a person each file that the approval lets run.
69
+
70
+ ```ts
71
+ defineExtension({
72
+ name: "stack",
73
+ executables: {
74
+ requires: [{ name: "python3", reason: "The tool run_tests runs pytest on it." }],
75
+ provides: [{ name: "slot-setup", path: "bin/slot-setup.sh" }],
76
+ },
77
+ });
78
+ ```
79
+
80
+ | Key | Entry | Rule |
81
+ | ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
82
+ | `requires` | `{ name, reason }` | `name` is a program name with no `/`: a letter or a digit, then letters, digits, `.`, `_`, `+` and `-`, at most 64. `reason` is one sentence, and it is required. A program that is not on `PATH` is `X008`. |
83
+ | `provides` | `{ name, path }` | `name` follows the same rule. `path` is relative to the package folder and inside it, with no `..`. A file that is missing or has no execute bit is `X009`. An approval covers the bytes of the file. |
84
+
85
+ The build writes the key `executables`, with both lists, only when the extension declares an entry. The engine refuses a manifest that breaks a rule with `X001`. A command finds a provided executable by its `name`: `edgar start` copies each one into `bin/` of the state folder, which is first on the `PATH` of each sandbox command and read-only. So a check or a `ctx.sandbox.exec` call writes `slot-setup`, not a path. Two enabled extensions that provide the same name are `X010`. No folder name makes a file a command: a file in `bin/` that `provides` does not name is only a file.
86
+
87
+ ### `defineTool(spec)`
88
+
89
+ | Key | Required | What it does |
90
+ | ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
91
+ | `description` | Yes | The text that a model reads when it chooses a tool. |
92
+ | `input` | Yes | The input schema, as Zod 4 or as a plain JSON Schema through `jsonSchema<T>(schema)`. The engine checks each input against it before the tool runs. |
93
+ | `output` | Yes | The output schema. A tool with no output schema does not compile. The engine checks each `done` output against it. |
94
+ | `execute(input, ctx)` | Yes | The tool. It returns an outcome. |
95
+ | `secrets` | No | The names of the secrets that the tool reads through `ctx.secrets`. |
96
+ | `capabilities` | No | The capabilities that the call gets. |
97
+ | `approval` | No | `"never"` (default), `"once"` for each run, `"always"` for each call, or `{ auto(input, ctx) }`, which may only tighten. |
98
+ | `side_effect`, `compensate`, `lookup` | No | A tool with an effect names its undo tool and its lookup tool, or says `undo: "none"` with an `undo_reason`. |
99
+
100
+ `disableTool(tool)` ships a tool turned off. A project turns it on with `[tools] enabled`.
101
+
102
+ ### The capabilities
103
+
104
+ | Capability | What it allows |
105
+ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
106
+ | `network:<host>` | `fetch` to that host. A call to any other host fails with `refused` before it connects. |
107
+ | `sandbox:read`, `sandbox:write` | `ctx.sandbox.read`, and `ctx.sandbox.write` and `ctx.sandbox.exec`. |
108
+ | `git:push` | A push of one `edgar/` branch of the run's work to origin: the call asks `git push origin <branch>` and `git rev-parse --verify <ref>`, with no flag, no `+` and no `src:dst`. The engine does the push itself, never forced, with the git credentials of the machine, after its secret file scan; git in the sandbox holds no credential. No other command runs without `sandbox:write`. |
109
+ | `tracker:read`, `tracker:write` | `ctx.tracker`: the tracker's reads, and its writes. |
110
+ | `runs:read` | `ctx.runs.read(runId)`. |
111
+ | `complete` | `ctx.complete(key, outcome)`, which completes a waiting attempt. |
112
+
113
+ ### The tool context, `ctx`
114
+
115
+ | Member | What it gives |
116
+ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
117
+ | `operation_id`, `run_id`, `stage`, `attempt` | The ids of the call. `operation_id` is the same on every retry of one operation and unique across stores, so a tool with an effect keys its write on it. |
118
+ | `signal` | An `AbortSignal` that fires when the engine cancels the call. Pass it to `fetch`. |
119
+ | `config` | The project's `[extensions.<name>]` table, which the engine validated against the extension's `config` schema. Parse it with that schema before use. |
120
+ | `secrets.get(name)`, `secrets.bytes(name)` | A declared secret, for this call only. Its bytes are zeroed when `execute` returns. A read after the call throws. |
121
+ | `sandbox.read`, `sandbox.write`, `sandbox.exec` | The run's sandbox. Each returns a `PortResult`: a refusal is a value, never a throw. |
122
+ | `tracker` | The tracker's methods, through the engine. |
123
+ | `runs.read(runId)` | A run, its attempts and its calls. |
124
+ | `complete(key, outcome)` | Completes a waiting attempt with `key`. |
125
+ | `progress(snapshot)`, `log(line)` | A `call_progress` event, and a `runtime_log` line. |
126
+
127
+ A `PortError` has a `code`: `capability_refused`, `sandbox_refused`, `runtime_payload_too_large`, `unknown_id`, `call_ended` or `engine_error`.
128
+
129
+ ### Return an outcome
130
+
131
+ | Function | Outcome |
132
+ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
133
+ | `done(output)` | The work is complete. |
134
+ | `skipped()` | There was nothing to do. |
135
+ | `temporaryFailure(kind, message, { retryAfterSeconds, cause })` | A later try can succeed. `kind` is a temporary kind. |
136
+ | `permanentFailure(kind, message, { cause })` | A later try cannot succeed. `kind` is a permanent kind. |
137
+ | `failure(kind, message, options)` | The temporary or the permanent form, chosen by `kind`. |
138
+ | `waiting(key, timeoutAt)` | The answer comes later, through `complete(key, outcome)`. |
139
+ | `fetchFailure(error, signal, context)` | The failure of a `fetch` that threw: `cancelled`, `refused` for a host outside the call's capabilities, or a temporary `provider_unavailable`. |
140
+ | `vendorFailure(kind, context, cause, headers, resetHeader)` | The failure of a vendor's answer. A rate limit waits for `Retry-After`, then the reset header, then one minute. |
141
+
142
+ A tool that throws ends as `permanent_failure(tool_error)`, which the engine never retries. For each kind, see [events and outcomes](/docs/concepts/events-and-outcomes.md#outcomes).
143
+
144
+ ### Trackers, hooks and environments
145
+
146
+ - `defineTracker(spec)` makes the extension a tracker of the project that maps its `[extensions.<name>.columns]`: `list_cards`, `card`, `comments`, `attachments`, `comment`, `move`, `set_labels`, `create_card`, `close`, `whoami` and `person`. The engine sweeps it with engine states; the extension maps them to its columns with `[extensions.<name>.columns]` and answers engine states. `card` answers `not_found` for a card that is archived or deleted, also when the vendor can still read it: the engine reads a card that a listing no longer has, and only `not_found` or a column that is not mapped says that the card left.
147
+ - The card block helpers read and write the fenced `edgar:v0` TOML block in a card's description, so each tracker keeps the block in the same form. `readBlock(description)` answers `ok(null)` for no block, the parsed `CardBlock`, or `permanent_failure(invalid)` with the TOML line or the fields that do not match in `cause`. `withBlock(description, block)` replaces the block, or adds it at the end. `blockLine(key, value)` is the TOML line of `batch`, `fingerprint` or `waits_for` that a search of descriptions finds. `normalFingerprint(raw)` lowercases a fingerprint of 16 or more hex characters and cuts it to 16. `sighted(block, at)` counts one more sighting at `at`, or answers `null` when `at` is not newer than `last_seen`, as for a retry. `oneAtATime(key, run)` runs `run` after every earlier call of `key` in the process has settled, so two calls that file one fingerprint cannot both miss the card the other files.
148
+ - `defineHook({ on, secrets, capabilities, check })` runs before (`before_tool`) or after (`after_tool`) each tool call that `[hooks] order` names it for. `check` returns `pass()`, or `deny(code, reason)`, which ends the call `permanent_failure(denied_by_hook)` with the reason.
149
+ - `defineEventHook({ events, secrets, capabilities, deliver })` gets the events of each run whose kind is in `events`, in order and at least once. `deliver(event, ctx)` answers `done({})` once it took the event. A failure has the engine hand the event again, up to five times. Use it to tell people about a run in a chat or by mail.
150
+ - `endNote(event, style, consoleUrl?)` writes the note at the end of a run from its `run_outcome` event. It answers `{ what, outcome, card, assignee, lines, facts }`; `outcome` is the run's outcome as the engine names it, such as `done` or `permanent_failure`. `lines` are, in order: who the card is assigned to, the card, what EDGAR did, and what the run used. `assignee` is the name of the person the card is assigned to, as the card has it, and is there only for an assigned card. When it is set, the first of `lines` is the line that names that person, so a medium that can mention a person writes its own first line. `what` is the one thing a person must know: `opened` (a pull request), `merged`, `approved`, `changes` or `closed` (what people decided on the pull request, from the `reviewed` record of the `end` of a run with a card; a run with no card, such as a schedule that reads each pull request, never says a decision; `facts` then has `approvedBy`, the logins that approved, and `commit`, the first 7 characters of the merge commit of a merged pull request, and the lines carry no summary of the proposal), `decision`, `waits` (the run decided to wait, so it did not finish, and its line says what it waits on), `failed`, `stopped`, `done` or `recovered`. `facts` holds the same note as plain values that no style changed, for a medium that lays the note out by itself, as `@kana-ai/edgar-ext-slack` does: the run, how long it took, its tokens (left out for a run with no model token) and cost, the address of the run's page, the workflow, each pull request as `{ url, label }`, with `referenced: true` for one that the run did not open but worked on or found, the risk sentence, the summary and the options of the proposal, and for a failed run its stage, its message as the engine wrote it, and `why`, that message in plain words when its failure word is a known one. `notePull(url, number, referenced?)` gives the `{ url, label }` of one pull request, with the label `<repository>#<number>` and `referenced: true` when you pass it, or `undefined` for an address that is not `http` or `https`. "I opened" names only the pull requests that the run opened; the note links each other one after what the run did, as "See the pull request:". After the pull requests, the note says "The merge risk is <risk>: <the first sentence of risk_reason>." when the `end` record has a `risk` that is one word other than `low`. `style` says how your medium writes a link and makes a text safe: `{ link: (url, label) => string, text: (text) => string }`. Pass `consoleUrl` only when people can open the console at that address. When the `end` or the `totals` of a payload does not read, the note is written from the `outcome` alone, so it still says whether the run finished. It answers `undefined` for any other event, and for a `run_outcome` payload whose `outcome` it cannot read, so say in your medium that the run is over. `cardLine(card, style)` writes the card line alone, and `noteCard(runCard.parse(payload))` reads the card of a `run_created` payload, so the first message about a run can name its card as the end note does.
151
+ - `defineEnvironment({ prepare, start, health, stop })` declares a service's running stack, each step a tool. A service names it with `[services.<name>] environment = { provider = "<ext>__<name>" }`. The stack is up only for a `check` stage, and one stack of a service is up at a time: a `check` stage that waits for it gives back its slot and takes the stack in the order the stages asked. For each `check` stage, the engine calls `stop` first, because a crash, a timeout or a failed `stop` can leave a stack up. Then it calls `prepare`, `start` and `health`, runs the checks, and calls `stop` again, also after a failed step. Each step gets the input `{ service, slot, run }`, where `slot` is always 1 and `run` is the sandbox's run, so a fixed port or Compose project name is safe. A failed step before the checks fails the stage with the step's name; a failed last `stop` writes an `alert`, and the next stage's first `stop` tries again. Each step must therefore be idempotent. A step that grants `sandbox:read` or `sandbox:write` runs in the run's sandbox.
152
+ - `defineService({ secrets, capabilities, run })` declares the extension's long-lived service, such as a listener on a chat platform's socket. `edgar start` runs it once the manifest is approved, and starts it again with a backoff when it stops by itself. `run(ctx, input)` gets the project's `[services]` in `input.services`, each with its `name`, `repo` and `default_branch`. The service opens cards with `ctx.cards.open`, puts a person's reply on the card of a run, or on a card by its key, with `ctx.cards.reply({ run } | { card }, text, by, origin)`, where `origin` is the place the reply came from, which the run that it starts names as `relayed`, starts the workflow `chat` on a message with no card with `ctx.runs.chat(text, by, origin, card)`, and sends a person's moves with `ctx.moves` and `ctx.runs.cancel`. With the capability `tracker:write`, it also posts on a card with `ctx.tracker.comment`. Every other tracker method and sandbox port is refused.
153
+
154
+ ## Build the manifest
155
+
156
+ Run `edgar-extension-build src/index.ts` in the extension's folder, usually as its `build` script. It imports the module once in a child process with an empty environment, and never runs a tool. It writes the manifest and one input and one output schema for each tool, and prints each file. It refuses, with exit code 1, a tool, hook, service, tracker or environment step that holds a secret and asks for a `network:<host>` that no secret it holds lists, and names the host and the secret to add it to:
157
+
158
+ ```bash
159
+ edgar-extension-build src/index.ts
160
+ ```
161
+
162
+ ```text
163
+ edgar-extension.json
164
+ schemas/count_lines.in.json
165
+ schemas/count_lines.out.json
166
+ ```
167
+
168
+ The manifest of the extension above:
169
+
170
+ ```json
171
+ {
172
+ "contract": 1,
173
+ "name": "notes",
174
+ "version": "0.1.0",
175
+ "config_schema": null,
176
+ "secrets": [],
177
+ "capabilities": ["sandbox:read"],
178
+ "tools": [
179
+ {
180
+ "name": "count_lines",
181
+ "description": "Count the lines of a file in the sandbox",
182
+ "input_schema": "schemas/count_lines.in.json",
183
+ "output_schema": "schemas/count_lines.out.json",
184
+ "secrets": [],
185
+ "capabilities": ["sandbox:read"],
186
+ "side_effect": false,
187
+ "approval": "never",
188
+ "disabled": false
189
+ }
190
+ ],
191
+ "webhooks": [],
192
+ "workflows": [],
193
+ "roles": [],
194
+ "skills": [],
195
+ "tracker": null,
196
+ "environments": [],
197
+ "hooks": []
198
+ }
199
+ ```
200
+
201
+ Commit `edgar-extension.json` and `schemas/`: they are what a person approves with `edgar extensions approve`. A change to either file after the approval makes `edgar start` refuse the extension with `X003`.
202
+
203
+ ## Test a tool
204
+
205
+ `testContext(options)` gives a tool context with fixed ids, the given `secrets` and `config`, and a sandbox that refuses each call except the given `exec`. `mockOrigin(origin)` installs a mock HTTP origin with no real network, records each request in `seen`, and answers each with the reply that you queue. This test runs on `node --test`:
206
+
207
+ ```ts
208
+ import assert from "node:assert/strict";
209
+ import { test } from "node:test";
210
+ import { testContext } from "@kana-ai/edgar-sdk/testing";
211
+ import notes from "ext-notes";
212
+
213
+ test("a read the sandbox refuses is a permanent failure", async () => {
214
+ const tool = notes.tools?.["count_lines"];
215
+ assert.ok(tool !== undefined);
216
+ const outcome = await tool.execute({ path: "README.md" }, testContext());
217
+ assert.deepEqual(outcome, {
218
+ outcome: "permanent_failure",
219
+ kind: "forbidden",
220
+ message: "not in this test",
221
+ });
222
+ });
223
+ ```
224
+
225
+ ```text
226
+ ✔ a read the sandbox refuses is a permanent failure
227
+ ℹ tests 1
228
+ ℹ pass 1
229
+ ℹ fail 0
230
+ ```
231
+
232
+ For tests with `mockOrigin`, see the tests of the `logs` extension in [`with-custom-extension`](/examples/with-custom-extension/README.md).
233
+
234
+ ## Secrets and the network
235
+
236
+ - Secrets reach a tool only through `ctx.secrets`, for the length of one call. Their bytes are zeroed when the call ends.
237
+ - `fetch` reaches only the hosts of the call's `network:<host>` capabilities. A tool that the engine hands a secret keeps only the `network:<host>` of that secret's hosts, so a secret lists each host that its calls reach, a redirect target and `127.0.0.1` included. `edgar-extension-build` refuses a manifest that does not, and `edgar check` reports the same mistake in a manifest that another tool wrote. `edgar extensions approve` prints these hosts for each secret as "its calls reach". A host that differs for each project, such as an SMTP server, is not in the manifest: the project names it in `[extensions.<name>] hosts`, and the engine adds it to the `network:<host>` capabilities of every call and to the hosts of every secret of the extension, so the runtime sees it as one more capability.
238
+ - The runtime replaces `http.request` and `https.request` with stubs that throw. It checks every TCP connection, such as `net.connect`, `tls.connect`, `http2.connect` or an undici `Agent` of your own, against the same hosts, and refuses UDP. See [the extension runtime](/apps/runtime/README.md).
239
+
240
+ ## Failures are values
241
+
242
+ A failure that correct code expects is a value, not an exception. Examples are a validation error, a missing item, a conflict, a vendor refusal and a network error. A function that can fail in this way returns a `Result`. Import the result helpers from `@kana-ai/edgar-sdk` or from `@kana-ai/edgar-sdk/result`.
243
+
244
+ ```ts
245
+ type Result<T, E> =
246
+ | { readonly ok: true; readonly value: T }
247
+ | { readonly ok: false; readonly error: E };
248
+ ```
249
+
250
+ - `ok(value)` makes a success. `err(error)` makes a failure.
251
+ - Check `ok` before you read `value` or `error`. The compiler refuses `r.value` until `r.ok` is `true`.
252
+ - At a call site, send a failure up with `if (!r.ok) return r;`.
253
+ - A `Result` is a plain object. It survives `JSON.stringify` and the engine's wire, and it needs no `instanceof`.
254
+ - The names are lower case. `Ok` and `Err` are the types of the two sides, and `ok` and `err` are the functions that make them.
255
+
256
+ The engine ports already answer this way: `ctx.sandbox.read(path)` returns a `PortResult<string>`, which is a `Result<string, PortError>`.
257
+
258
+ ### The one rule for `throw`
259
+
260
+ Throw only for a bug: a broken invariant that correct code never reaches. Catch it only at the top. For a tool, the top is the SDK's runtime: a tool that throws ends as `permanent_failure(tool_error)`, which the engine never retries. Do not catch a bug to turn it into a failure value. For example, a secret that a tool reads after its call ended throws, and the GitHub and Linear clients read their token before the request, so a missing token does not look like a network failure that the engine retries.
261
+
262
+ ### Helpers
263
+
264
+ The examples below use this function.
265
+
266
+ ```ts
267
+ import { type Result, err, ok } from "@kana-ai/edgar-sdk/result";
268
+
269
+ const parseCount = (text: string): Result<number, string> =>
270
+ /^\d+$/.test(text) ? ok(Number(text)) : err(`${text} is not a count`);
271
+ ```
272
+
273
+ `attempt(run, onThrow)` calls a function that throws for an expected failure, such as `JSON.parse`. `onThrow` turns the caught value, which has the type `unknown`, into your error.
274
+
275
+ ```ts
276
+ attempt<unknown, string>(
277
+ () => JSON.parse("[1]"),
278
+ () => "not JSON",
279
+ ); // { ok: true, value: [1] }
280
+ attempt<unknown, string>(
281
+ () => JSON.parse("{"),
282
+ () => "not JSON",
283
+ ); // { ok: false, error: "not JSON" }
284
+ ```
285
+
286
+ `attemptAsync(run, onThrow)` does the same for a function that returns a promise, such as `fetch`. It also catches a throw that occurs before the promise exists.
287
+
288
+ ```ts
289
+ const sent = await attemptAsync(
290
+ async () => await fetch("https://api.example.com/items", { signal: ctx.signal }),
291
+ (caught) => fetchFailure(caught, ctx.signal, "example GET /items"),
292
+ );
293
+ if (!sent.ok) return sent.error; // a temporary `provider_unavailable`, or `cancelled`
294
+ ```
295
+
296
+ `map(r, f)` changes the value of a success. A failure passes through.
297
+
298
+ ```ts
299
+ map(parseCount("2"), (n) => n * 10); // { ok: true, value: 20 }
300
+ map(parseCount("x"), (n) => n * 10); // { ok: false, error: "x is not a count" }
301
+ ```
302
+
303
+ `mapError(r, f)` changes the error of a failure, for example a `PortError` into a tool `Failure`. A success passes through.
304
+
305
+ ```ts
306
+ mapError(parseCount("x"), (message) => ({ code: "invalid", message }));
307
+ // { ok: false, error: { code: "invalid", message: "x is not a count" } }
308
+ ```
309
+
310
+ `andThen(r, f)` runs a next step that can also fail. The first failure stops the chain, and the error type is the union of both.
311
+
312
+ ```ts
313
+ const half = (n: number): Result<number, "odd"> => (n % 2 === 0 ? ok(n / 2) : err("odd"));
314
+ andThen(parseCount("8"), half); // { ok: true, value: 4 }
315
+ andThen(parseCount("7"), half); // { ok: false, error: "odd" }
316
+ ```
317
+
318
+ `unwrapOr(r, fallback)` gives the value, or `fallback` for a failure. Use it only when nobody needs to know about the failure.
319
+
320
+ ```ts
321
+ unwrapOr(parseCount("x"), 0); // 0
322
+ ```
323
+
324
+ `all(results)` gives every value in order, or the first failure.
325
+
326
+ ```ts
327
+ all(["1", "2"].map(parseCount)); // { ok: true, value: [1, 2] }
328
+ all(["1", "x"].map(parseCount)); // { ok: false, error: "x is not a count" }
329
+ ```
330
+
331
+ `expectOk(r, message)` gives the value of a success. For a failure, it throws an `Error` with `message`, and the failure's error as `cause`. Use it only where a failure is a bug, such as a literal that you know is valid.
332
+
333
+ ```ts
334
+ expectOk(parseCount("4"), "a literal count parses"); // 4
335
+ expectOk(parseCount("x"), "a literal count parses"); // throws Error("a literal count parses", { cause: "x is not a count" })
336
+ ```
337
+
338
+ ### Limits
339
+
340
+ - No compiler or lint rule finds a dropped `Result`. A bare `parseCount("x");` compiles and lints clean. Look for it in review. The lint gate does find a dropped promise, including a dropped `attemptAsync(...)`, through `no-floating-promises` with `checkThenables`.
341
+ - A `default` arm with `x satisfies never` is checked by the compiler and erased at run time, so the arm must also `throw new Error("unreachable")`.
342
+ - `unwrapOr` and `all` drop information: `unwrapOr` drops the error, and `all` keeps only the first failure.
343
+ - A `Result` holds no stack trace. Keep the vendor's raw code in the failure's `cause`.
344
+
345
+ ## Rate and usage limits
346
+
347
+ A vendor tells a caller how much of its limit is left: GitHub and Linear in `X-RateLimit-*` headers, Anthropic in `anthropic-ratelimit-*` headers, many others in `Retry-After`. A tool passes these facts to the engine as a `Limit`, on a failure and on a success. The engine keeps the newest limit of each source in its `limits` table, does not start a stage whose source is used up before the reset, and shows each source on the console's Limits page and on `GET /api/limits`.
348
+
349
+ ```ts
350
+ interface Limit {
351
+ source: string; // the host or the provider, such as "api.github.com" or "claude"
352
+ remaining?: number; // calls or tokens left in the window
353
+ limit?: number; // the size of the window
354
+ resets_at?: number; // when the window resets, in Unix milliseconds
355
+ window?: string; // the vendor's name for the window, such as "core" or "complexity"
356
+ }
357
+ ```
358
+
359
+ `resets_at` is in Unix milliseconds, the same unit as `timeout_at`, so the engine compares it with its clock and needs no parse.
360
+
361
+ | Export | What it does |
362
+ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
363
+ | `limitFromHeaders(headers, scheme, source, now?)` | Reads the limit one answer reports, or `undefined` when it reports none |
364
+ | `reportLimit(ctx, limit)` | Keeps the limit of an answer for the call of `ctx`. The runtime puts the newest one on the call's outcome when the outcome carries none |
365
+ | `done(output, { limit })` | A success with a limit |
366
+ | `temporaryFailure`, `permanentFailure`, `failure` | Take `limit` in their options, next to `retryAfterSeconds` and `cause` |
367
+ | `vendorFailure(kind, context, cause, headers, from)` | A failure from a vendor answer, with the limit of its headers. `from` is `{ scheme, source }` |
368
+ | `reportedLimit(ctx)` (from `@kana-ai/edgar-sdk/testing`) | The newest limit reported on `ctx`, for a unit test |
369
+
370
+ The schemes:
371
+
372
+ | Scheme | Headers | Reset as |
373
+ | ------------- | ------------------------------------------------------------------------------------------------- | ----------------- |
374
+ | `github` | `x-ratelimit-limit`, `-remaining`, `-reset`; the window from `x-ratelimit-resource` | Unix seconds |
375
+ | `linear` | `x-ratelimit-requests-*` (window `requests`) and `x-ratelimit-complexity-*` (window `complexity`) | Unix milliseconds |
376
+ | `anthropic` | `anthropic-ratelimit-{requests,tokens,input-tokens,output-tokens}-*` | An RFC 3339 date |
377
+ | `draft` | `ratelimit-limit`, `-remaining`, `-reset` of the IETF draft | Seconds from now |
378
+ | `retry_after` | None | - |
379
+
380
+ - An epoch reset above 10^12 is read as milliseconds, else as seconds.
381
+ - When a scheme has more than one window, the window with the smallest share left wins.
382
+ - `Retry-After`, in seconds or as an HTTP date, is read with every scheme. It makes the limit used up (`remaining: 0`) until the time it names.
383
+ - A header that is not a whole number, or is empty, is left out. A family counts when any one of its three headers is present.
384
+
385
+ `vendorFailure` with `rate_limited` waits until `resets_at`, else one minute, and marks the limit used up until then. With any other kind, it carries the limit of the headers when there is one.
386
+
387
+ A client reports the limit of each answer, and maps a failure with the same `from`:
388
+
389
+ ```ts
390
+ export const limits = { scheme: "github", source: "api.github.com" } as const satisfies LimitFrom;
391
+
392
+ const response = await fetch(`https://${limits.source}/repos/shop/api`, { signal: ctx.signal });
393
+ reportLimit(ctx, limitFromHeaders(response.headers, limits.scheme, limits.source));
394
+ if (!response.ok)
395
+ return vendorFailure("rate_limited", "GET repo", "status:429", response.headers, limits);
396
+ ```
397
+
398
+ What the engine does with a limit:
399
+
400
+ - A failure that is `rate_limited` counts as a hit: the row's `hits` goes up by one, and `last_hit_at` is set. The count starts again on each UTC day.
401
+ - A stage whose provider, or one of whose tool's `network:<host>` hosts, has `remaining: 0` and a `resets_at` in the future does not start. The engine records `waited_for_limit` with the source and the time, and starts the stage at the reset.
402
+ - A limit with no `resets_at` never holds a stage, because nothing says when it ends.
403
+
404
+ Limits of this design:
405
+
406
+ - An outcome carries one limit, the newest. A tool that calls two hosts in one call reports only the host it called last.
407
+ - A tool must name the same `source` as its `network:<host>` capability, or the engine cannot hold the stage on it.
408
+
409
+ ## Tests
410
+
411
+ ```bash
412
+ pnpm --filter @kana-ai/edgar-sdk run test
413
+ ```
414
+
415
+ The tests are in `tests/`, mirroring `src/`, and run on `node --test` in process, with no network: an HTTP call goes to `mockOrigin`.
416
+
417
+ ## Validation
418
+
419
+ These commands were run on 2026-11-10 on macOS with Node 26, in a scratch package that links this SDK and holds the `notes` extension above:
420
+
421
+ | Command | Exit code |
422
+ | ------------------------------------------------------------------------------------ | ------------------------ |
423
+ | `tsc --noEmit` on `src/index.ts`, with the repository's `tools/typescript/base.json` | 0 |
424
+ | `edgar-extension-build src/index.ts` | 0, the three files above |
425
+ | `node --test` with the test above | 0, `pass 1` |
426
+
427
+ ## Where to read next
428
+
429
+ - [`with-custom-extension`](/examples/with-custom-extension/README.md): an extension with a secret, a host, a failure table and its tests, built, approved and called from a workflow.
430
+ - [The extension runtime](/apps/runtime/README.md): the process that runs an extension.
431
+ - [Events and outcomes](/docs/concepts/events-and-outcomes.md): what the engine does with each outcome.
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env node
2
+ import { type Result } from "#outcome/result";
3
+ /** Reads the `version` of a `package.json` text. */
4
+ export declare function packageVersion(text: string): Result<string, string>;
5
+ /** Imports `entry` once in a child process with a scrubbed environment and writes `edgar-extension.json` and its schemas into `folder`; any failure to read its `package.json` is refused. */
6
+ export declare function build(entry: string, folder: string): Promise<Result<readonly string[], string>>;
@@ -0,0 +1,110 @@
1
+ #!/usr/bin/env node
2
+ import { spawn } from "node:child_process";
3
+ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
4
+ import { tmpdir } from "node:os";
5
+ import { dirname, join, resolve } from "node:path";
6
+ import { fileURLToPath, pathToFileURL } from "node:url";
7
+ import { isExtension } from "#define/extension";
8
+ import { formatJson } from "#build/json";
9
+ import { toManifest, unlistedHosts } from "#build/manifest";
10
+ import { andThen, attempt, attemptAsync, err, ok } from "#outcome/result";
11
+ /** Reads the `version` of a `package.json` text. */
12
+ export function packageVersion(text) {
13
+ const parsed = attempt(() => JSON.parse(text), () => "package.json is not JSON");
14
+ return andThen(parsed, (json) => typeof json === "object" &&
15
+ json !== null &&
16
+ "version" in json &&
17
+ typeof json.version === "string"
18
+ ? ok(json.version)
19
+ : err("package.json has no string version"));
20
+ }
21
+ /** Imports `entry` once in a child process with a scrubbed environment and writes `edgar-extension.json` and its schemas into `folder`; any failure to read its `package.json` is refused. */
22
+ export async function build(entry, folder) {
23
+ const path = join(folder, "package.json");
24
+ const text = await attemptAsync(async () => await readFile(path, "utf8"), (caught) => `cannot read ${path}: ${errorCode(caught)}`);
25
+ if (!text.ok)
26
+ return text;
27
+ const version = packageVersion(text.value);
28
+ if (!version.ok)
29
+ return version;
30
+ const home = await mkdtemp(join(tmpdir(), "edgar-build-"));
31
+ try {
32
+ const child = await collect(resolve(folder, entry), version.value, folder, home);
33
+ if (!child.ok)
34
+ return child;
35
+ const written = [];
36
+ for (const [path, value] of child.value) {
37
+ const target = join(folder, path);
38
+ await mkdir(dirname(target), { recursive: true });
39
+ await writeFile(target, formatJson(value));
40
+ written.push(path);
41
+ }
42
+ return ok(written);
43
+ }
44
+ finally {
45
+ await rm(home, { recursive: true, force: true });
46
+ }
47
+ }
48
+ async function collect(entry, version, cwd, home) {
49
+ const child = spawn(process.execPath, ["--disable-proto=throw", fileURLToPath(import.meta.url), "--collect", entry, version], {
50
+ cwd,
51
+ env: { PATH: process.env["PATH"] ?? "", HOME: home },
52
+ stdio: ["ignore", "ignore", "pipe", "ipc"],
53
+ });
54
+ const stderr = [];
55
+ let files;
56
+ child.stderr?.on("data", (chunk) => stderr.push(chunk));
57
+ child.on("message", (message) => {
58
+ if (Array.isArray(message) && message.every(isEntry))
59
+ files = message;
60
+ });
61
+ const code = await new Promise((settle) => child.on("close", settle));
62
+ if (code !== 0)
63
+ return err(Buffer.concat(stderr).toString("utf8").trim() || `exit ${String(code)}`);
64
+ return files === undefined ? err("the build child sent no manifest") : ok(files);
65
+ }
66
+ function errorCode(error) {
67
+ return error instanceof Error && "code" in error ? String(error.code) : String(error);
68
+ }
69
+ function isEntry(value) {
70
+ return Array.isArray(value) && value.length === 2 && typeof value[0] === "string";
71
+ }
72
+ async function collectInChild(entry, version) {
73
+ const module = await import(pathToFileURL(entry).href);
74
+ const extension = typeof module === "object" && module !== null && "default" in module
75
+ ? module.default
76
+ : undefined;
77
+ if (!isExtension(extension)) {
78
+ process.stderr.write(`${entry} has no default export made by defineExtension\n`);
79
+ process.exitCode = 1;
80
+ return;
81
+ }
82
+ const built = toManifest(extension, version);
83
+ const unlisted = unlistedHosts(built.manifest);
84
+ if (unlisted.length > 0) {
85
+ process.stderr.write(`${unlisted.join("\n")}\n`);
86
+ process.exitCode = 1;
87
+ return;
88
+ }
89
+ process.send?.([["edgar-extension.json", built.manifest], ...built.files]);
90
+ process.disconnect?.();
91
+ }
92
+ if (import.meta.main) {
93
+ const [mode, entry, version] = process.argv.slice(2);
94
+ if (mode === "--collect" && entry !== undefined && version !== undefined) {
95
+ await collectInChild(entry, version);
96
+ }
97
+ else if (mode === undefined || mode.startsWith("-")) {
98
+ process.stderr.write("usage: edgar-extension-build <entry module>\n");
99
+ process.exitCode = 2;
100
+ }
101
+ else {
102
+ const result = await build(mode, process.cwd());
103
+ if (result.ok)
104
+ process.stdout.write(`${result.value.join("\n")}\n`);
105
+ else {
106
+ process.stderr.write(`${result.error}\n`);
107
+ process.exitCode = 1;
108
+ }
109
+ }
110
+ }
@@ -0,0 +1,2 @@
1
+ /** `value` as the JSON text oxfmt keeps as it is: each object key on its own line, an array on one line when it fits in 100 columns, and a longer array of numbers filled several to a line. */
2
+ export declare function formatJson(value: unknown): string;