@1outres/dsh-plugin-claude-subscription 0.3.0 → 0.4.0

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 1outres
+Copyright (c) 2026 Nous Research and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,12 +1,14 @@
 # @1outres/dsh-plugin-claude-subscription
 
-Makes Claude models selectable in DeepSeek Harness through your own `claude login`.
-Every call goes through
-[`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk).
-DSH keeps its own loop, tools, sessions and UI.
+Use your own Claude subscription as an LLM provider in DeepSeek Harness (DSH).
 
-This plugin is meant for your own subscription and your own personal use. Check that your use
-fits Anthropic's terms for your plan.
+This plugin is unofficial. It is not affiliated with or endorsed by Anthropic.
+
+DSH keeps its agent loop, tools, approvals and compaction. For each model call,
+the plugin runs the official `claude` CLI once, in `-p` stream-json mode, behind a
+small relay on the loopback address. The relay lets exactly one request reach
+Anthropic and refuses every other request from that process. The CLI's own tools
+are off, so the model can only call the tools DSH offers, and DSH runs them.
 
 Install just this plugin:
 
@@ -18,187 +20,128 @@ Or install it with every plugin in the repository through the
 [`@1outres/dsh-plugins`](../dsh-plugins) bundle. Enable one or the other: both
 insert the same `claude-subscription` row.
 
-## What it adds
-
-A provider route `claude-subscription` with a fixed model list:
-
-| Model               | Context window |
-| ------------------- | -------------- |
-| `claude-fable-5-1`  | 1,000,000      |
-| `claude-opus-5-5`   | 1,000,000      |
-| `claude-sonnet-5-5` | 1,000,000      |
-| `claude-haiku-5-5`  | 1,000,000      |
-
-The context windows are the `modelUsage[model].contextWindow` values of a real call. A model
-your plan does not allow fails at call time. Efforts are `low`, `medium`, `high`, `xhigh` and
-`max`. Thinking is adaptive and summarized on all four models. Images work in user messages and
-in tool results.
-
-The plugin has no settings and no browser half. Its row id is `claude-subscription`.
-
 ## Requirements
 
-- Run `claude login` once, in the same user account that runs DSH. The plugin never reads,
-  stores or logs credentials. The SDK's child process uses the stored login.
-- About 330 MB of disk on Linux x64. The SDK ships the Claude Code binary (323 MB unpacked), and
-  this is why the `@1outres/dsh-plugins` bundle install gets large too.
-- Tested on Linux x64 only.
-
-## How a call works
-
-Each DSH step starts a new `query()`. The whole history goes in as a synthesized transcript
-through `sessionStore.load` and `resume`, with an empty prompt. DSH runs every tool: the plugin
-declares tools to the CLI, reads tool calls from the stream, and stops the child at
-`message_delta`. A tool handler never runs a tool and never returns a result.
-
-### The pinned SDK
-
-`@anthropic-ai/claude-agent-sdk` is pinned to exactly `0.3.318`. The transcript format, the seal
-entry, `CLAUDE_AGENT_SDK_MCP_NO_PREFIX`, `alwaysLoad`, the alpha `sessionStore`, the
-`onProcessSpawned` hook and the temp dir redirect are all undocumented or unstable behavior,
-verified on this version only. Run the
-contract test below before you move the pin. The SDK's own peers (`zod`,
-`@modelcontextprotocol/sdk`, `@anthropic-ai/sdk`) are not declared: the plugin needs none of them
-at runtime, and an install without them only prints a peer warning.
-
-### What the CLI always adds
-
-No option or variable removes these from what the model reads:
-
-- the Claude Code identity prefix before your system prompt
-- an environment section (working directory, platform, and so on)
-- the current date
-- a reminder that names your account email
-
-### What ends up in DSH session data
-
-`replayState` stores what the CLI emitted, so that the cache keeps working. That includes the
-working directory, your account email and your organization UUID. They stay in your DSH session
-logs. Treat those logs as personal data if you share them.
-
-The working directory is the one the DSH process started in.
-
-### Isolation
-
-- `env` is a strict allow-list. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`,
-  `CLAUDE_CODE_OAUTH_TOKEN`, cloud-provider variables and `DSH_*` never reach the child.
-- `settingSources: []`, built-in tools off and auto-compaction off keep `~/.claude` out of it.
-
-### The billing guard
-
-Before the first step, the plugin starts the CLI with a prompt that yields nothing, reads
-`initializationResult()`, and closes it. This sends no model request, which the contract test
-checks in the CLI's debug log. A pass is remembered until the plugin stops. A failure is not.
+- DSH 0.2.1-rc.5 or newer in the 0.2 line. Windows is not
+  supported.
+- The official Claude Code CLI, installed:
 
-- `subscriptionType` must be present and `apiProvider` must be `firstParty`. The CLI sets
-  `subscriptionType` only for an OAuth login with the inference scope, whatever the plan is called.
-- `apiKeySource` must be absent or `none`. The SDK types say every other current value is an API
-  key, and that the old values such as `oauth` are no longer sent. A Console login reports
-  `/login managed key`, so it fails with `API_KEY_SOURCE_REJECTED`.
-- With no subscription and no API key, the call fails with `MISSING_CREDENTIAL`.
+  ```sh
+  npm install -g @anthropic-ai/claude-code
+  ```
 
-Each step and each login refresh still checks `apiKeySource` at `system/init`. That is a second
-line only: `init` arrives just before the first request, and the child lives for about 2 seconds
-after it is stopped. So if the login changes to an API key while the plugin runs, one request may
-go out and be billed to the API. The error says so.
+- A login, made as the same user that DSH runs as:
 
-### The private temp dir
+  ```sh
+  claude auth login
+  ```
 
-While a step runs, the SDK keeps a copy of your access token in a `claude-resume-*` dir. A killed
-parent leaves that dir behind. So the plugin uses
-`$XDG_CACHE_HOME/dsh-plugin-claude-subscription/<pid>-<host>-<pid namespace>-<random>/`, or
-`~/.cache/...` when `XDG_CACHE_HOME` is not set. The root and the dir are mode 700, and the plugin
-refuses a root that is a symlink, is not yours, or is open to others.
+The login belongs to the CLI. The plugin never opens or copies credential files,
+has no login flow of its own, and asks for no API key. When the CLI is logged out,
+a call fails with a message that tells you to run `claude auth login`.
 
-At startup it removes leftovers on this host without reading the files in them:
+The plugin refuses to run when the environment of DSH sends the CLI to another
+backend. It fails with `CONFLICTING_ENVIRONMENT` and names the variables, never
+their values. These are `ANTHROPIC_BASE_URL`, `CLAUDE_CODE_USE_BEDROCK`,
+`CLAUDE_CODE_USE_VERTEX` and `CLAUDE_CODE_USE_FOUNDRY`.
 
-- A dir from the same PID namespace goes when its process is dead. A reused PID looks alive, so
-  that dir stays until a later start finds the PID free.
-- A PID from another namespace cannot be checked here, for example from `bwrap --unshare-pid` with
-  a shared `~/.cache`. Such a dir goes only once it is older than 7 days. If its process is still
-  idle by then, the SDK makes the dir again at the next step.
-- A dir from another host stays, because its process cannot be checked.
+## Settings
 
-When the plugin stops, it stops every child and waits up to 5 seconds for each one to exit. It
-kills a child still alive at that point, and then removes the dir. If the removal fails, it logs a
-warning. A step started after that fails with `PLUGIN_DISPOSED`.
+The plugin has no settings page. Set these fields in your profile's
+`cordis.patch.yml`:
 
-The wait uses the child's PID, not the SDK's own cleanup. A busy child gets `SIGTERM` after 2
-seconds, the SDK removes `claude-resume-*` at that moment, and the child then writes its transcript
-there while it exits. So when a query that was stopped mid-stream ends this way, a
-`claude-resume-*` dir with that transcript and no token copy can stay in the private dir until the
-plugin stops.
-
-SDK 0.3.318 picks that location from the parent's `os.tmpdir()`, not from `options.env.TMPDIR`. So
-`sessionStore.load` sets `process.env.TMPDIR` in the DSH process for one moment and restores it at
-the next check phase of the event loop. The contract test checks that the copy lands in the
-private dir.
-
-## Options and errors
-
-`maxTokens` sets `CLAUDE_CODE_MAX_OUTPUT_TOKENS`. `temperature` and `stop` have no equivalent, so
-they raise `UNSUPPORTED_OPTION`. This means DSH's experimental auto-review, which sends
-`temperature: 0`, cannot use this route.
-
-| Failure                                      | Code                                           | DSH retries |
-| -------------------------------------------- | ---------------------------------------------- | ----------- |
-| Not logged in, or a failed login refresh     | `MISSING_CREDENTIAL`                           | no          |
-| Usage limit, with the reset time when known  | `QUOTA`                                        | no          |
-| Prompt too long                              | `CONTEXT_WINDOW_EXCEEDED`                      | compacts    |
-| Rate limit, server, connection or timeout    | `RATE_LIMIT`, `SERVER`, `TRANSPORT`, `TIMEOUT` | yes         |
-| No output                                    | `EMPTY_RESPONSE`                               | yes         |
-| The model declined                           | `REFUSAL`                                      | no          |
-| Model not in your plan                       | `UNKNOWN_MODEL`                                | no          |
-| Account needs action (on hold, verification) | `CLAUDE_ACCOUNT`                               | no          |
-| Bad request                                  | `INVALID_REQUEST`                              | no          |
-| An API key would be used                     | `API_KEY_SOURCE_REJECTED`                      | no          |
-| A cloud provider would be used               | `NOT_SUBSCRIPTION_LOGIN`                       | no          |
-| The child process failed                     | `CLAUDE_CODE_PROCESS`                          | no          |
-| The plugin has stopped                       | `PLUGIN_DISPOSED`                              | no          |
-
-An abort gives the `aborted` finish. The login check and the login refresh each have a deadline
-(30 and 60 seconds), and passing it gives `TIMEOUT`.
-
-`CLAUDE_CODE_MAX_RETRIES` is `0`, so DSH owns the retry policy. The CLI's default of 10 retries
-would multiply with DSH's 5, up to 66 requests with long silent waits. The CLI's recovery from a
-bad image or a rejected thinking block still works with `0`, as checked with real calls.
-
-### Problems the CLI recovers from by itself
-
-The CLI can drop a bad image and still end in success. DSH's stream has no warning chunk, so the
-plugin logs these at `warn` and records them in `replayState.response.healedErrors`. They do not
-show in the Web UI.
-
-A rejected thinking signature is also recovered, but the CLI reports it only in its debug log.
-The plugin cannot see it.
-
-### Expired login: not verified against a real expiry
-
-The SDK removes the refresh token from the copy a step uses, so a step cannot renew the login. On
-`authentication_failed` with status 401, or the CLI's "session expired" wording, the plugin runs
-one non-resume `query()` with `persistSession: false`, then retries the step once. If either
-fails, it raises the login error.
-
-A real expiry cannot be reproduced on demand. This path is unit tested, and the contract test
-only checks that the non-resume call starts and succeeds. It has never run against a token that
-really expired.
-
-## Tests
-
-`pnpm test` at the repository root runs the unit tests, with the SDK's `query` mocked. Some of them
-replay `test/fixtures/*.jsonl`, frames recorded from real calls on SDK 0.3.318 with only a whitelist
-of fields kept. They hold no ids, account data or paths, and must stay that way because this repo is
-public.
-
-The contract test makes real calls on your subscription, and it guards SDK upgrades. It is not
-part of `pnpm test`.
-
-```sh
-pnpm --filter @1outres/dsh-plugin-claude-subscription test:contract
+```yaml
+- id: claude-subscription
+  config:
+    claudeConfigDir: ~/.claude-work
 ```
 
-It proves with a nonce that an earlier turn is seen, runs a tool round trip, and shows cache reads
-past the system prompt. It also checks that the login check sends no request, the errors for an
-invalid model and for no login, thinking replay, the output cap, images, the private temp dir,
-abort, dispose with a running child, and the non-resume call. It uses `claude-haiku-5-5`. Set
-`CLAUDE_SUBSCRIPTION_CONTRACT_MODEL` to try another model.
+DSH reads the edit when it recomposes the profile. Without its HMR plugin, restart
+DSH instead.
+
+| Field                    | Default  | Meaning                                                                                                                                        |
+| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `command`                | `claude` | Name found through `PATH`, or an absolute path.                                                                                                |
+| `claudeConfigDir`        | empty    | Config directory of a separate Claude login. Empty uses `CLAUDE_CONFIG_DIR` from the environment, then the CLI's own default.                  |
+| `claudeCodeTelemetry`    | on       | Lets the CLI send its telemetry and fetch feature flags. The flags unlock models in its picker, so turning this off can shrink the model list. |
+| `readIdleTimeoutSeconds` | `1800`   | Seconds of silence from the CLI before a call fails with `TIMEOUT`. From 1 to 2147483.                                                         |
+
+Whatever the settings say, the CLI is started with `DISABLE_AUTOUPDATER`,
+`DISABLE_FEEDBACK_COMMAND` and `CLAUDE_CODE_DISABLE_TERMINAL_TITLE`.
+
+The relay reads `https_proxy`, `http_proxy` and `NO_PROXY` from the environment of
+DSH. Only an `http://` proxy that supports `CONNECT` works. Any other proxy URL
+fails the call, and the plugin does not connect directly instead. Set
+`CLAUDE_CODE_GZIP_REQUEST_BODIES=0` to send request bodies uncompressed.
+
+## Models
+
+The model list comes from the CLI's answer about your account. Pinned routes the
+answer leaves out are added after it, except models Anthropic grants per
+organization. If the CLI cannot answer, for example when it is logged out, no
+model is listed, and the message appears on the provider's row under
+**Settings → Models**. The next look at the list asks the CLI again.
+
+A pinned 1M model is sent with `[1m]`. An id the plugin does not know is sent as it
+is and reports a 200K window. An unknown id that ends in `[1m]` reports no window.
+
+## What the model sees
+
+The CLI adds its own text to every request. Besides the DSH system prompt and
+history, the request holds:
+
+- A first system block with the CLI's version and the caller name, for example
+  `x-anthropic-billing-header: cc_version=2.1.317.173; cc_entrypoint=deepseek-harness;`.
+- A second system block: `You are a Claude agent, built on Anthropic's Claude Agent SDK.`
+- A `# Environment` block, sent as a `system` message after the first user turn.
+  It lists the working directory, whether it is a git repository, the platform, the
+  shell and the OS version. It adds a note on downloaded files, the model's name
+  and id, its knowledge cutoff and today's date.
+
+The working directory in that block is a private directory the plugin keeps for the
+CLI, not your workspace. The DSH system prompt names the real one.
+
+A user turn that ends in text starting with `/` reaches the model with one leading
+space. Without the space the CLI reads the text as a slash command, even with
+`--disable-slash-commands`, and the call fails.
+
+Text in this section was read from a request by Claude Code 2.1.317. Another CLI
+version can differ.
+
+## Known limits
+
+- Each model call starts a new `claude` process, so a call has more start-up time
+  than a direct API call.
+- The plugin relies on how the CLI behaves today: its replay of history, its
+  extra-body setting, and its stream-json output. A CLI update can change them.
+- Calls count against your subscription limits. Your account decides whether a model
+  uses usage credits. Some rows in the model list say so, and the plugin does not
+  block them.
+- DSH shows token counts for a call, but the plugin reports no cost.
+- A reply cut off by the output limit runs no tool call, and DSH sees `max-tokens`.
+- A refusal ends the call with `CONTENT_FILTER` and the reason the service gave. A
+  tool call in a refused reply never runs.
+- A reply that ends normally with no text and no tool call, even one with thinking,
+  fails with `EMPTY_RESPONSE`, which DSH retries. A reply cut off by the output limit
+  reports `max-tokens` instead.
+- A request whose retained images pass 20 MiB as base64 fails with `IMAGE_OFFLOAD_REQUIRED`.
+  DSH then offloads the oldest images and retries. A dropped image keeps a text note that
+  names its read-only path when DSH has one.
+- `temperature` is checked and then dropped. It never reaches the model.
+- DSH removes variables with `TOKEN` in their names before it starts a child process,
+  so `CLAUDE_CODE_OAUTH_TOKEN` in the environment of DSH does not reach the CLI. Log in
+  with `claude auth login` instead.
+- The relay trusts Node's bundled certificate list and `NODE_EXTRA_CA_CERTS`. A
+  TLS-inspecting proxy whose certificate is only in `SSL_CERT_FILE` fails the call.
+- Every call declares the full active tool list, so adding or removing a tool during a
+  conversation rewrites the prompt cache from that point.
+- Signed thinking is replayed only for a message that was not edited, was made by the
+  same model that the request names, and holds text or a tool call besides its thinking.
+  Any other message, such as an edited one or one from before a model switch, is sent
+  again as plain text and tool calls.
+
+## Attribution
+
+Ported from the `claude-subscription-directsdk` plugin of
+[NousResearch/hermes-official-plugins](https://github.com/NousResearch/hermes-official-plugins),
+at commit `83f0a89`, MIT licensed. See `LICENSE`.