superagent-claude 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ok0
+
+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/NOTICE

@@ -0,0 +1,118 @@
+superagent-claude
+Copyright (c) 2026 ok0
+
+This project includes material ported or adapted from dsh-superagent-prototype
+(https://github.com/deepseek-ai/dsh-superagent-prototype), distributed under
+the MIT License reproduced below.
+
+----------------------------------------------------------------------
+MIT License
+
+Copyright (c) 2026 DeepSeek Harness Team
+
+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.
+----------------------------------------------------------------------
+
+Ported files
+------------
+Each ported file starts with the header "// Ported from dsh-superagent-prototype (MIT) <reference path>" (Markdown files: "<!-- Ported from dsh-superagent-prototype (MIT) <reference path> -->").
+
+prompts/admission.md <- prompts/admission.md
+prompts/dispatch.md <- prompts/dispatch.md
+prompts/handoff-router.md <- prompts/handoff-orchestrator.md
+prompts/handoff-worker.md <- prompts/handoff-worker.md
+prompts/handoff.md <- prompts/handoff.md
+prompts/replies.md <- prompts/replies.md
+prompts/router.md <- prompts/orchestrator.md
+prompts/shared.md <- prompts/shared.md
+prompts/subscriptions.md <- prompts/subscriptions.md
+prompts/team/communication.md <- prompts/team/communication.md
+prompts/team/delivery.md <- prompts/team/delivery.md
+prompts/team/scope.md <- prompts/team/scope.md
+prompts/work.md <- prompts/work.md
+prompts/worker.md <- prompts/worker.md
+skills/github.md <- skills/dsh-superagent-github/SKILL.md
+src/app/assessment.ts <- src/app/assessment.ts
+src/app/cache.ts <- src/app/cache.ts
+src/app/cards.ts <- src/app/cards.ts
+src/app/effects.ts <- src/app/effects.ts
+src/app/kv.ts <- src/kv.ts
+src/app/links.ts <- src/app/links.ts (with triggerMessage from src/executor/dsh.ts)
+src/app/notices.ts <- src/app/notices.ts
+src/app/outbox.ts <- src/app/outbox.ts
+src/app/passes.ts <- src/app/passes.ts
+src/app/prompts.ts <- src/app/prompts.ts
+src/app/resources.ts <- src/app/resources.ts
+src/app/store.ts <- src/app/store.ts
+src/app/store-read.ts <- src/app/store-read.ts
+src/app/tools/executor.ts <- src/app/tools/executor.ts
+src/app/tools/main.ts <- src/app/tools/main.ts
+src/app/tools/tool.ts <- src/app/tools/tool.ts
+src/app/versions.ts <- src/app/versions.ts
+src/core/assignments.ts <- src/core/assignments.ts
+src/core/engine.ts      <- src/core/engine.ts
+src/core/errors.ts      <- src/core/errors.ts
+src/core/evals.ts       <- src/core/evals.ts
+src/core/ids.ts         <- src/core/ids.ts
+src/core/index.ts       <- src/core/index.ts
+src/core/intake.ts      <- src/core/intake.ts
+src/core/memory.ts      <- src/core/memory.ts
+src/core/model.ts       <- src/core/model.ts
+src/core/part.ts        <- src/core/part.ts
+src/core/ports.ts       <- src/core/ports.ts
+src/core/reasons.ts     <- src/core/reasons.ts
+src/core/replies.ts     <- src/core/replies.ts
+src/core/stage.ts       <- src/core/stage.ts
+src/core/tickets.ts     <- src/core/tickets.ts
+src/executor/recovery.ts <- src/executor/dsh.ts (restart recovery)
+src/infra/commands.ts <- src/infra/commands.ts
+src/infra/health.ts <- src/infra/health.ts
+src/infra/paths.ts <- src/infra/paths.ts
+src/infra/text.ts <- src/infra/text.ts
+src/policy/admission.ts <- src/admission.ts
+src/policy/limits.ts    <- src/limits.ts
+src/policy/policy.ts    <- src/policy.ts
+src/sources/admission-context.ts <- src/sources/admission-context.ts
+src/sources/github/channel.ts <- src/sources/github-channel.ts
+src/sources/github/pull.ts <- src/sources/github-pull.ts
+src/sources/github/read.ts <- src/sources/github-read.ts
+src/sources/github/source.ts <- src/sources/github.ts
+src/sources/github/trigger.ts <- src/sources/github-trigger.ts
+src/sources/host.ts <- src/sources/host.ts (with sourceContextOf from src/app/source-context.ts)
+src/sources/kind.ts <- src/sources/kind.ts
+src/sources/poll.ts <- src/sources/poll.ts
+src/sources/registry.ts <- src/sources/registry.ts
+tests/admission-context.spec.ts <- tests/admission-context.spec.ts
+tests/assessment.spec.ts <- tests/assessment.spec.ts
+tests/cache.spec.ts <- tests/cache.spec.ts
+tests/core-engine.spec.ts <- tests/core-engine.spec.ts
+tests/effects.spec.ts <- tests/effects.spec.ts
+tests/followups.spec.ts <- tests/followups.spec.ts
+tests/fixtures/async.ts <- tests/fixtures/async.ts
+tests/fixtures/engine.ts <- tests/core-engine.spec.ts (harness)
+tests/fixtures/host.ts <- tests/fixtures/host.ts (rewritten over the fake runtime)
+tests/github-read.spec.ts <- tests/github-read.spec.ts
+tests/outbox.spec.ts <- tests/outbox.spec.ts
+tests/passes.spec.ts <- tests/passes.spec.ts
+tests/policy.spec.ts    <- tests/policy.spec.ts
+tests/queue.spec.ts <- tests/queue.spec.ts (L28)
+tests/registry.spec.ts <- tests/registry.spec.ts
+tests/router-tools.spec.ts <- tests/tools.spec.ts (Router cases)
+tests/stage.spec.ts     <- tests/stage.spec.ts
+tests/store.spec.ts <- tests/store.spec.ts

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# superagent-claude
 
-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.
+superagent-claude is a proactive coding agent for GitHub repositories. Powered by Claude. It polls the repositories you configure. When a person on the allowlist asks it for work, it opens a ticket, does the work in its own session and git worktree, and answers in the original conversation, for example with a pull request.
+
+Take as little human attention as possible, and give as much value as possible. The agent acts only when an allowed person asks or when a rule you wrote allows it, and it speaks only when someone must act or can use a result.
+
+![Flow: an allowed person mentions the agent, allowlist admission, a ticket, its own session and git worktree, then a reply comment or a pull request](docs/assets/flow.svg)
+
+## Quick start
+
+```sh
+npm i -g superagent-claude
+export SUPERAGENT_CLAUDE_GITHUB_TOKEN=<agent account token>
+export ANTHROPIC_API_KEY=<API key>                     # either: API key
+export CLAUDE_CODE_OAUTH_TOKEN=<token>                 # or: Claude subscription (token from `claude setup-token`)
+superagent-claude start --config superagent-claude.json
+```
+
+It needs Node.js 22.19 or later. `npx superagent-claude start --config superagent-claude.json` runs it without a global install.
+
+`auth.mode` picks which one (`api-key` or `subscription`); Bedrock and Vertex also work. See [docs/authentication.md](docs/authentication.md) for both modes and the subscription terms warning.
+
+The config needs `repositories`, `policy.allowed` and `auth.mode`. See [docs/getting-started.md](docs/getting-started.md), which also covers building from source.
+
+A container image is published as `ghcr.io/ok0/superagent-claude`. See [Docker](docs/deploy.md#docker) to run it.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md): install, agent account, start
+- [Configuration](docs/configuration.md): settings and defaults
+- [Authentication](docs/authentication.md): auth modes and start refusals
+- [Runtime contract](docs/runtime-contract.md)
+- [Deploy](docs/deploy.md): run as a service
+- [Security](docs/security.md): trust policy
+- [Contributing](CONTRIBUTING.md): setup, checks and pull requests
+
+## Test repositories
+
+Live tests write only to the repository named by `SUPERAGENT_CLAUDE_LIVE_REPO` and may read the optional `SUPERAGENT_CLAUDE_LIVE_REPORT_REPO`. Without these settings the live tests that need GitHub are skipped. Seed the playground with `pnpm live:seed` (`pnpm live:seed --upgrade` replaces an older seed in one commit) and clean it with `pnpm live:cleanup`. See [Run live tests against your own playground](CONTRIBUTING.md#run-live-tests-against-your-own-playground). The project's own live runs use [ok0/superagent-claude-playground](https://github.com/ok0/superagent-claude-playground) as the playground.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/lib/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// src/infra/redact.ts
+/** Masking of secret values and token shapes in text shown to people or written to logs. */
+const REDACTED = "[redacted]";
+function redactor(env, mask = "***") {
+	const values = [];
+	for (const [name, value] of Object.entries(env)) if (typeof value === "string" && value.length >= 8 && /(TOKEN|SECRET|PASSWORD|API_KEY|ACCESS_KEY|CREDENTIAL)/i.test(name)) values.push(value);
+	return (text) => {
+		let out = text;
+		for (const value of values) out = out.split(value).join(mask);
+		return out.replace(/\bgh[pousr]_[A-Za-z0-9_]{16,}/g, mask).replace(/\b[A-Za-z]+_pat_[A-Za-z0-9_]{16,}/g, mask).replace(/\bsk-ant-[A-Za-z0-9_-]{8,}/g, mask).replace(/x-access-token:[^@\s]+@/g, `x-access-token:${mask}@`);
+	};
+}
+function redact(text, env, mask = "***") {
+	return redactor(env, mask)(text);
+}
+function logFormat(argv, env) {
+	let value = env["SUPERAGENT_CLAUDE_LOG_FORMAT"] || void 0;
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--config") i++;
+		else if (arg === "--log-format") {
+			value = argv[i + 1];
+			if (value === void 0) return void 0;
+			i++;
+		}
+	}
+	if (value === void 0) return "text";
+	return value === "text" || value === "json" ? value : void 0;
+}
+// src/cli/bin.ts
+/** After main() returns, the process exits on its own; if something still holds the event loop, it is ended this long after. */
+const EXIT_GRACE_MS = 3e3;
+const argv = process.argv.slice(2);
+const json = argv[0] === "start" && logFormat(argv.slice(1), process.env) === "json";
+const mask = redactor(process.env, REDACTED);
+const event = (level, name, detail) => mask(JSON.stringify({
+	level,
+	at: (/* @__PURE__ */ new Date()).toISOString(),
+	event: name,
+	detail
+})) + "\n";
+if (json) {
+	process.removeAllListeners("warning");
+	process.on("warning", (warning) => {
+		process.stdout.write(event("warn", "node.warning", `${warning.name}: ${warning.message}`));
+	});
+	process.on("uncaughtException", (error) => {
+		process.stdout.write(event("error", "cli.failed", String(error)));
+		process.exit(1);
+	});
+}
+const exitSoon = () => {
+	setTimeout(() => {
+		process.exit();
+	}, EXIT_GRACE_MS).unref();
+};
+import("./main-Br6CBO2s.js").then(({ main }) => main(argv, {
+	out: (s) => {
+		process.stdout.write(s);
+	},
+	err: (s) => {
+		process.stderr.write(s);
+	},
+	cwd: process.cwd(),
+	env: process.env,
+	signals: process
+})).then((code) => {
+	process.exitCode = code;
+	exitSoon();
+}, (error) => {
+	if (json) process.stdout.write(event("error", "cli.failed", String(error)));
+	else process.stderr.write(`superagent-claude: ${String(error)}\n`);
+	process.exitCode = 1;
+	exitSoon();
+});
+export { redactor as i, REDACTED as n, redact as r, logFormat as t };