@1outres/dsh-plugin-claude-subscription 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1outres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# @1outres/dsh-plugin-claude-subscription
 
-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.
+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.
+
+This plugin is meant for your own subscription and your own personal use. Check that your use
+fits Anthropic's terms for your plan.
+
+Install just this plugin:
+
+```sh
+dsh plugin add @1outres/dsh-plugin-claude-subscription
+```
+
+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.
+
+- `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`.
+
+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.
+
+### The private temp dir
+
+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.
+
+At startup it removes leftovers on this host without reading the files in them:
+
+- 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.
+
+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 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
+```
+
+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.

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Installs this plugin on its own (dsh plugin add @1outres/dsh-plugin-claude-subscription).
+# The @1outres/dsh-plugins bundle inserts the same "claude-subscription" row, so select
+# one bundle or the other, never both.
+- insert:
+    - id: claude-subscription
+      name: "@1outres/dsh-plugin-claude-subscription"