@kana-ai/edgar-provider-claude 0.1.2 → 0.1.3

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.
package/README.md CHANGED
@@ -19,8 +19,9 @@ Each session is one Claude Agent SDK `query()` (`@anthropic-ai/claude-agent-sdk`
19
19
  - A new session gets a new handle. `resume: {handle, fork: false}` continues that session under the same handle. `resume: {handle, fork: true}` starts a new handle from its history.
20
20
  - `model` is the vendor's model id from `[providers.claude] model` in `edgar.toml`, sent to the SDK as `model`. With no such key, the engine sends the role's `model`, which is `claude`: the runtime then sends no model, and the SDK uses its default model.
21
21
  - A turn ends `done` with what the model passed to `edgar__result` once the engine accepted it. A role without `edgar__result` ends `done` with the turn's last text.
22
+ - Each `session.send` after a `result` is the next user message of the same session, so a role with `steer` gets a comment from the team as a new turn with its context kept. A send while a turn runs is `busy`, so the engine holds the comment until the turn's `result`.
22
23
  - A role's `effort` is the SDK's `effort`. A role with no `effort` runs at the default of the model.
23
- - `limits.max_turns` is the SDK's `maxTurns`. `limits.context_tokens` sets `CLAUDE_CODE_AUTO_COMPACT_WINDOW`. `limits.max_tokens` counts each model call's input and output tokens once, and stops the session `token_budget` when the total passes it.
24
+ - `limits.max_turns` is the SDK's `maxTurns`. `limits.context_tokens` sets `CLAUDE_CODE_AUTO_COMPACT_WINDOW`. `limits.max_tokens` counts each model call's tokens once, new input, cache reads, cache writes and output, and stops the session `token_budget` when the total passes it.
24
25
  - One mapping table in `src/outcome/failures.ts` turns the SDK's errors into outcome kinds, and keeps the raw code in `cause` (`assistant:<code>`, `status:<HTTP status>`, `terminal:<reason>`, `result:<subtype>`). A 429 with a known reset time is `rate_limited` with `retry_after`; a 429 without one, a 5xx, a 529 and a lost process are temporary; a 401, a 403 and a login failure are `unauthenticated`. A code the table does not know is `provider_unavailable`.
25
26
  - Each SDK `rate_limit_event` becomes a `limit` event of the source `claude`: `remaining` is `0` when the status is `rejected`, `resets_at` is `resetsAt` in milliseconds, and `window` is the `rateLimitType`, such as `five_hour`. The engine stores it on the `claude` row of the `limits` table and does not start an agent stage of a Claude role while that row is used up. The `utilization` share is not read.
26
27
  - A line over 4 MiB is refused with `runtime_payload_too_large`. The runtime exits after `--idle-seconds` (default 300) with no turn running, and cancels each open session before it exits.
@@ -28,15 +29,16 @@ Each session is one Claude Agent SDK `query()` (`@anthropic-ai/claude-agent-sdk`
28
29
  ## What the runtime and the CLI may reach
29
30
 
30
31
  ```bash
31
- env -i PATH="$PATH" HOME=<per-run folder> \
32
- node --disable-proto=throw --permission --allow-child-process \
33
- --allow-fs-read=<apps/provider-claude> --allow-fs-read=<packages/sdk> \
34
- --allow-fs-read=<node_modules/.pnpm> \
32
+ env -i PATH="$PATH" HOME=<per-run folder> TMPDIR=<per-run folder>/tmp NODE_OPTIONS= \
33
+ node --disable-proto=throw --permission \
34
+ --allow-fs-read=<apps/provider-claude> --allow-fs-read=<per-run folder> \
35
+ --allow-fs-read=<each linked package folder> \
36
+ --allow-fs-write=<per-run folder>/tmp --allow-child-process \
35
37
  apps/provider-claude/src/main.ts --idle-seconds 300
36
38
  ```
37
39
 
38
- - The runtime starts with `PATH` and `HOME` only. No credential is in its environment: each arrives in `session.start`.
39
- - The SDK starts the Claude CLI as a child with an environment of `PATH`, `HOME` and exactly one credential: `CLAUDE_CODE_OAUTH_TOKEN` for `oauth`, `ANTHROPIC_API_KEY` for `api_key`. The engine's fallback API key comes as an `api_key` credential too, so it reaches the CLI as `ANTHROPIC_API_KEY`. The CLI uses an `ANTHROPIC_AUTH_TOKEN` or an API key over an OAuth token when it has both, so it never gets two.
40
+ - The runtime starts with `PATH`, `HOME`, `TMPDIR` and an empty `NODE_OPTIONS` only. `HOME` is an empty folder for each run, `providers/<run>/` in the state folder, and `HOME/tmp` is its `TMPDIR` and the one folder it may write. No credential is in its environment: each arrives in `session.start`.
41
+ - The SDK starts the Claude CLI as a child with an environment of `PATH`, `HOME` and exactly one credential: `CLAUDE_CODE_OAUTH_TOKEN` for `oauth`, `ANTHROPIC_API_KEY` for `api_key`. The engine's fallback API key, and a person's own key saved under **Your keys** in the console, come as an `api_key` credential too, so they reach the CLI as `ANTHROPIC_API_KEY`. The CLI uses an `ANTHROPIC_AUTH_TOKEN` or an API key over an OAuth token when it has both, so it never gets two.
40
42
  - The `cli` credential carries no value: the child gets `PATH`, `HOME` set to `--cli-home` (the `HOME` of the user who runs `edgar start`), and `USER` and `LOGNAME` set to that user's account name from the system. It uses the sign-in of `claude auth login` that it finds there. On macOS that sign-in is in the keychain under `USER`, so the CLI is not signed in without it. The role's tools are the engine's, so they still run in the run's sandbox.
41
43
  - An `unauthenticated` outcome's message names its fix: `claude auth login` or `ANTHROPIC_API_KEY` for the `cli` credential, else the secret of the credential it ran on.
42
44
  - The SDK finds the CLI itself: it resolves `@anthropic-ai/claude-agent-sdk-<platform>-<arch>/claude` (or `-musl` on musl Linux) from its own package, which pnpm installs as an optional dependency for the current machine only. So `pathToClaudeCodeExecutable` is not set. A container needs the package of its own platform.
@@ -11,7 +11,7 @@ export declare class Reader {
11
11
  constructor(spec: SessionStartParams, now?: () => number);
12
12
  /** Keeps what the model passed to `edgar__result` once the engine accepted it. */
13
13
  capture(output: unknown): void;
14
- /** True once the session spent more input and output tokens than `limits.max_tokens`. */
14
+ /** True once the session spent more tokens than `limits.max_tokens`: new input, cache reads, cache writes and output. */
15
15
  get overBudget(): boolean;
16
16
  /** The events one SDK message gives. */
17
17
  read(message: SDKMessage): SessionEvent[];
@@ -25,7 +25,7 @@ export class Reader {
25
25
  capture(output) {
26
26
  this.#captured = { value: output };
27
27
  }
28
- /** True once the session spent more input and output tokens than `limits.max_tokens`. */
28
+ /** True once the session spent more tokens than `limits.max_tokens`: new input, cache reads, cache writes and output. */
29
29
  get overBudget() {
30
30
  if (this.#maxTokens === undefined)
31
31
  return false;
@@ -38,7 +38,10 @@ export class Reader {
38
38
  read(message) {
39
39
  if (message.type === "assistant") {
40
40
  const usage = message.message.usage;
41
- this.#spent.set(message.message.id, usage.input_tokens + usage.output_tokens);
41
+ this.#spent.set(message.message.id, usage.input_tokens +
42
+ usage.output_tokens +
43
+ (usage.cache_read_input_tokens ?? 0) +
44
+ (usage.cache_creation_input_tokens ?? 0));
42
45
  if (message.error !== undefined)
43
46
  this.#assistantError = message.error;
44
47
  if (message.parent_tool_use_id !== null)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kana-ai/edgar-provider-claude",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "The process that runs Claude sessions for the EDGAR engine through the Claude Agent SDK, over JSON-RPC on stdio.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -20,8 +20,8 @@
20
20
  },
21
21
  "dependencies": {
22
22
  "@anthropic-ai/claude-agent-sdk": "0.3.319",
23
- "@kana-ai/edgar-contracts": "0.1.2",
24
- "@kana-ai/edgar-sdk": "0.1.2",
23
+ "@kana-ai/edgar-contracts": "0.1.3",
24
+ "@kana-ai/edgar-sdk": "0.1.3",
25
25
  "zod": "4.6.7"
26
26
  },
27
27
  "devDependencies": {