superagent-claude 0.2.0 → 0.3.1

package/README.md

@@ -20,7 +20,7 @@ It needs Node.js 22.19 or later. `npx superagent-claude start --config superagen
 
 `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.
+The config needs `repositories` and `policy.allowed`; `auth.mode` defaults to `api-key` and needs its credential. 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.
 

package/lib/cli.js

@@ -55,7 +55,7 @@ const exitSoon = () => {
 		process.exit();
 	}, EXIT_GRACE_MS).unref();
 };
-import("./main-DKxToYW7.js").then(({ main }) => main(argv, {
+import("./main-CingWi3i.js").then(({ main }) => main(argv, {
 	out: (s) => {
 		process.stdout.write(s);
 	},

package/lib/{main-DKxToYW7.js → main-CingWi3i.js}

@@ -13,7 +13,7 @@ import { DatabaseSync } from "node:sqlite";
 import { checkSync, lockSync } from "proper-lockfile";
 import { fileURLToPath } from "node:url";
 // package.json
-var version = "0.2.0";
+var version = "0.3.1";
 // src/infra/env.ts
 /**
 * Environment for subprocesses: only the inherited whitelist (PATH, HOME, LANG) plus explicitly named variables.
@@ -1438,6 +1438,7 @@ var Assignments = class extends EnginePart {
 		if (report.state === "blocked" || report.state === "failed") ticket.undelivered = ticket.undelivered.filter((id) => !automatic(ticket.inputs.find((input) => input.id === id)));
 		this.repo.tickets.save(ticket);
 		if (report.limit && report.state === "blocked") this.replies.limitStopped(ticket, assignment.id, report.limit, pull);
+		if (report.workspace && report.state === "blocked") this.replies.workspaceBlocked(ticket, assignment.id, summary);
 		const ready = !ticket.follows?.length ? "completed" : this.tickets.followsDone(ticket)?.outcome;
 		const outcome = report.state === "dropped" ? this.tickets.followsDone(ticket)?.outcome ?? "dropped" : report.state === "ready" ? ready : void 0;
 		if (outcome) this.tickets.end(ticketId, "executor", outcome, at);
@@ -2080,6 +2081,10 @@ function refusalText(reason) {
 function limitText(limit, pull) {
 	return `I stopped before finishing: the ${limit} limit for this task was reached.` + (pull ? ` Work so far: ${pull}.` : "") + " Reply here to continue.";
 }
+/** The note a person gets when a configured branch is missing, so the task could not start. */
+function workspaceBlockedText(reason) {
+	return `I could not start this task. ${reason} Reply here once that is fixed to try again.`;
+}
 /**
 * Each message is queued under a deterministic id, so it is never sent twice. Replies to a person go where the person's
 * message was written, and a result where the latest person's message to the ticket was written.
@@ -2118,6 +2123,24 @@ var Replies = class extends EnginePart {
 			ticketId: ticket.id
 		});
 	}
+	/**
+	* Queue the reason the task could not start where the latest person's message to the ticket was written, else where
+	* it started; nothing when there is no conversation. Its id is `workspace-blocked:<assignmentId>:<triggerId>` for
+	* the latest person's message, so a repeat or restart sends nothing more, and a person's reply that meets the same
+	* block is told again.
+	*/
+	workspaceBlocked(ticket, assignmentId, reason) {
+		const channel = this.replyChannel(ticket);
+		if (!channel) return;
+		const latest = ticket.inputs.findLast((input) => input.kind === "trigger" && input.human === true && !input.context)?.triggerId ?? (this.repo.triggers.get(ticket.origin.triggerId)?.human ? ticket.origin.triggerId : void 0);
+		this.options.outbox.send({
+			id: latest ? `workspace-blocked:${assignmentId}:${latest}` : `workspace-blocked:${assignmentId}`,
+			channel,
+			text: workspaceBlockedText(reason),
+			kind: "reply",
+			ticketId: ticket.id
+		});
+	}
 	withdrawAttention(attentionId) {
 		this.options.outbox.withdraw(key("attention-reply", attentionId));
 	}
@@ -2866,6 +2889,12 @@ function settingsPolicy(settings, sources) {
 }
 const DEFAULT_STATE_DIR = "~/.superagent-claude";
 const RepositorySchema = z.string().trim().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/, "must be owner/name");
+const BranchNameSchema = z.string().regex(/^(?![-/])(?!.*\.\.)(?!.*\/\/)(?!.*\/$)(?!.*\.lock$)[A-Za-z0-9._/-]{1,200}$/, "must be a branch name: letters, digits and . _ - /, not starting with - or /, without .. or //, not ending with / or .lock");
+const RepositoryEntrySchema = z.union([RepositorySchema, z.object({
+	repository: RepositorySchema,
+	branchFrom: BranchNameSchema.optional(),
+	pullRequestTo: BranchNameSchema.optional()
+}).strict()]);
 const AUTH_MODES = Object.keys(AUTH_ENV);
 /** A refused start (exit code 2); `rule` names the violated startup rule. */
 var StartupRefused = class extends Error {
@@ -2877,7 +2906,23 @@ var StartupRefused = class extends Error {
 	}
 };
 const ConfigSchema = z.object({
-	repositories: z.array(RepositorySchema).min(1, "must name at least one repository"),
+	repositories: z.array(RepositoryEntrySchema).min(1, "must name at least one repository").superRefine((items, ctx) => {
+		const seen = /* @__PURE__ */ new Set();
+		const reported = /* @__PURE__ */ new Set();
+		for (const item of items) {
+			const name = typeof item === "string" ? item : item.repository;
+			const key = name.toLowerCase();
+			if (seen.has(key)) {
+				if (!reported.has(key)) {
+					reported.add(key);
+					ctx.addIssue({
+						code: "custom",
+						message: `lists ${name} more than once`
+					});
+				}
+			} else seen.add(key);
+		}
+	}).transform((items) => items.map((item) => typeof item === "string" ? item : item.repository)),
 	policy: z.object({
 		allowed: z.array(LoginSchema).min(1, "must name at least one login"),
 		acceptMode: z.enum([
@@ -2932,6 +2977,24 @@ const ConfigSchema = z.object({
 	}),
 	stateDir: z.string().trim().min(1).default(DEFAULT_STATE_DIR)
 }).strict();
+function repositoryBranches(entries) {
+	const parsed = z.array(RepositoryEntrySchema).safeParse(entries);
+	if (!parsed.success) return {};
+	const branches = {};
+	for (const entry of parsed.data) {
+		if (typeof entry === "string") continue;
+		const { repository, branchFrom, pullRequestTo } = entry;
+		if (branchFrom === void 0 && pullRequestTo === void 0) continue;
+		branches[repository.toLowerCase()] = {
+			...branchFrom !== void 0 ? { branchFrom } : {},
+			...pullRequestTo !== void 0 ? { pullRequestTo } : {}
+		};
+	}
+	return branches;
+}
+function branchesOf(config, repository) {
+	return config.branches?.[repository.toLowerCase()] ?? {};
+}
 var ConfigError = class extends StartupRefused {
 	constructor(message) {
 		super("config", message);
@@ -2960,9 +3023,11 @@ function loadConfig(path, env = process.env) {
 	const result = ConfigSchema.safeParse(raw);
 	if (!result.success) throw new ConfigError(`The config file ${path} is invalid:\n` + result.error.issues.map((issue) => `  ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n"));
 	const data = result.data;
+	const branches = repositoryBranches(raw.repositories);
 	return {
 		...data,
-		stateDir: expandStateDir(data.stateDir, dirname(path), env)
+		stateDir: expandStateDir(data.stateDir, dirname(path), env),
+		...Object.keys(branches).length ? { branches } : {}
 	};
 }
 const byLogin = (a, b) => {
@@ -3001,18 +3066,8 @@ const SUBSCRIPTION_POLICY_WARNING = "auth.mode subscription runs the agent on a
 const SHARED_USE_WARNING = "ToS risk: with auth.mode subscription, people other than the subscription owner (policy.allowed is not exactly [auth.owner]) can make the agent work on the owner's subscription; this shared use may violate the subscription terms.";
 const SANDBOX_DOC = "docs/deploy.md#sandbox-in-containers";
 const UNSANDBOXED_WARNING = `security.allowUnsandboxed is true and the runtime sandbox is unavailable here: sessions run without the sandbox, network.allow is not enforced and commands can read the agent's tokens from other processes; restrict egress outside the agent (see ${SANDBOX_DOC})`;
-const RULE_NUMBER = {
-	credential: 1,
-	"allowed-empty": 2,
-	"repositories-empty": 3,
-	"agent-allowed": 4,
-	"subscription-shared": 6,
-	unsandboxed: 7,
-	"no-repository": 8
-};
 function refused(rule, text) {
-	const number = RULE_NUMBER[rule];
-	return new StartupRefused(rule, number ? `Startup refused (rule ${number}, ${rule}): ${text}` : `Startup refused (${rule}): ${text}`);
+	return new StartupRefused(rule, `Startup refused (${rule}): ${text}`);
 }
 const present = (value) => typeof value === "string" && value.trim() !== "";
 function resolveCredential(mode, env) {
@@ -3257,6 +3312,13 @@ var ReadLedger = class {
 };
 const DRAIN_MS = 2e3;
 const workerKey = (ticketId) => `worker-${ticketId}`;
+/** A configured branch is missing on the remote; the message is the reason a person reads. */
+var WorkspaceBlocked = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "WorkspaceBlocked";
+	}
+};
 /**
 * Mode of a ticket Input (see docs/runtime-contract.md): a person's message steers; notes, reopen markers and
 * a message no person wrote that waited on a ready ticket (`quiet`) are injected; everything else is a followup.
@@ -3542,6 +3604,14 @@ var WorkerExecutor = class {
 			try {
 				workspace = await this.deps.prepare(ticket);
 			} catch (e) {
+				if (e instanceof WorkspaceBlocked) {
+					this.report(ticketId, {
+						state: "blocked",
+						summary: e.message,
+						workspace: true
+					});
+					return;
+				}
 				this.report(ticketId, {
 					state: "failed",
 					summary: `The workspace could not be prepared: ${this.message(e)}`
@@ -6389,6 +6459,7 @@ function truncateOutput(text, maxLines, maxBytes) {
 * Clone and fetch get the injected access env (authentication), and errors mask its secrets.
 * Publishing pushes an agent branch without force, adding co-author trailers only to commits not yet pushed.
 * Access errors carry the HTTP status when one is known. A transient push failure is retried up to 3 times (2 s, 5 s).
+* A worktree starts from the configured remote branch, the branch choice is fixed per ticket in a host file outside the worktree, and a missing configured branch stops prepare or push with `WorkspaceBlocked`.
 */
 var RepositoryAccessError = class extends Error {
 	repository;
@@ -6491,7 +6562,30 @@ var Workspaces = class {
 	clonePath(repository) {
 		return join(this.stateDir, "repos", repository.replace("/", "__"));
 	}
-	async prepare(ticket, name) {
+	branchesPath(ticketId) {
+		return join(this.stateDir, "branches", ticketId + ".json");
+	}
+	fixedBranches(ticketId) {
+		const path = this.branchesPath(ticketId);
+		if (!existsSync(path)) return void 0;
+		const record = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof record !== "object" || record === null || Array.isArray(record)) throw new Error(`The branch record of ticket ${ticketId} is unreadable`);
+		const { from, to } = record;
+		if (from !== void 0 && typeof from !== "string" || to !== void 0 && typeof to !== "string") throw new Error(`The branch record of ticket ${ticketId} is unreadable`);
+		return {
+			...from !== void 0 ? { from } : {},
+			...to !== void 0 ? { to } : {}
+		};
+	}
+	remoteHas(clone, name) {
+		return this.git([
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			"refs/remotes/origin/" + name
+		], clone).then(() => true, () => false);
+	}
+	async prepare(ticket, name, branches = {}) {
 		if (!NAME.test(name) || name.includes("..") || name.endsWith(".lock")) throw new Error("Invalid worktree name: " + name);
 		const repository = this.repositoryOf(ticket);
 		if (!REPOSITORY.test(repository)) throw new RepositoryAccessError(repository, "not an owner/name repository");
@@ -6517,6 +6611,15 @@ var Workspaces = class {
 			const base = await this.clone(repository);
 			mkdirSync(dirname(cwd), { recursive: true });
 			await this.git(["worktree", "prune"], base);
+			const stored = this.fixedBranches(ticket.id);
+			const fixed = stored ?? {
+				...branches.branchFrom ? { from: branches.branchFrom } : {},
+				...branches.pullRequestTo ? { to: branches.pullRequestTo } : {}
+			};
+			const names = [...new Set([fixed.from, fixed.to].filter((name) => name !== void 0))];
+			const missing = [];
+			for (const name of names) if (!await this.remoteHas(base, name)) missing.push(name);
+			if (missing.length) throw new WorkspaceBlocked(`${repository} has no branch ${missing.join(", ")}, so no workspace was made. A person must create the branch or change branchFrom or pullRequestTo for ${repository} in the config.`);
 			const exists = await this.git([
 				"rev-parse",
 				"--verify",
@@ -6535,8 +6638,16 @@ var Workspaces = class {
 				"-b",
 				branch,
 				cwd,
-				"origin/HEAD"
+				fixed.from ? "origin/" + fixed.from : "origin/HEAD"
 			], base);
+			if (stored === void 0) {
+				const path = this.branchesPath(ticket.id);
+				mkdirSync(dirname(path), {
+					recursive: true,
+					mode: 448
+				});
+				writeFileSync(path, JSON.stringify(fixed) + "\n", { mode: 384 });
+			}
 			return {
 				repository,
 				cwd,
@@ -6580,6 +6691,7 @@ var Workspaces = class {
 		return dir;
 	}
 	async remove(ticketId) {
+		rmSync(this.branchesPath(ticketId), { force: true });
 		const path = this.worktreePath(ticketId);
 		if (!existsSync(path)) return;
 		const common = existsSync(join(path, ".git")) ? (await this.git([
@@ -6648,6 +6760,18 @@ var Workspaces = class {
 			"HEAD"
 		], cwd)).trim();
 	}
+	async reviewBase(cwd, repo) {
+		const configured = this.fixedBranches(basename(resolve(cwd)))?.from;
+		if (configured === void 0) return "origin/HEAD";
+		return await this.git([
+			...repo,
+			...GIT_READ_OPTIONS,
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			"refs/remotes/origin/" + configured
+		], cwd).then(() => true, () => false) ? "refs/remotes/origin/" + configured : "origin/HEAD";
+	}
 	async diffStat(cwd, base) {
 		const repo = this.repository(cwd);
 		const known = base !== void 0 && SHA.test(base) && await this.git([
@@ -6661,7 +6785,7 @@ var Workspaces = class {
 			...repo,
 			...GIT_READ_OPTIONS,
 			"merge-base",
-			"origin/HEAD",
+			await this.reviewBase(cwd, repo),
 			"HEAD"
 		], cwd)).trim();
 		const out = await this.git([
@@ -6742,7 +6866,13 @@ var Workspaces = class {
 			const branch = (await this.git(["branch", "--show-current"], cwd)).trim();
 			if (!branch.startsWith("agent/")) throw new Error("The worktree is not on its agent branch");
 			const clone = await this.clone(repository);
-			const base = (await this.git([
+			const fixed = this.fixedBranches(ticket.id);
+			const target = fixed?.to ?? fixed?.from;
+			let base;
+			if (target) {
+				if (!await this.remoteHas(clone, target)) throw new WorkspaceBlocked(`${repository} has no branch ${target} to open the pull request against, so nothing was pushed and no pull request was opened. A person must create the branch or change branchFrom or pullRequestTo for ${repository} in the config.`);
+				base = target;
+			} else base = (await this.git([
 				"symbolic-ref",
 				"--short",
 				"refs/remotes/origin/HEAD"
@@ -9019,7 +9149,8 @@ function readTool(description, grammar, read) {
 * Policy is checked before any git or GitHub call: live ticket, configured repository, a PR this ticket bound,
 * and delivery.allowAutoMerge. Publish re-checks push permission first and returns `published: false`
 * without any write when it is missing. Then the host review decision may stop it with `review_required`, again without any write.
-* Repository access errors file a failed report.
+* Repository access errors file a failed report. A configured target branch missing on the remote returns
+* `published: false` before any push.
 */
 const REVIEW_REASON = "Run the superagent-reviewer subagent before publishing, give it the original request and the human constraints, apply only bug and missing-requirement findings, then call orchestrator_publish again";
 /** The issue a Trigger is on: its meta names a repository and a number, and `isPr` is false. */
@@ -9081,7 +9212,7 @@ function deliveryTools(host, ticketId) {
 	return [
 		tool$1({
 			name: "orchestrator_publish",
-			description: "Push this ticket's commits and open its pull request, or reuse the open one for the branch; never force-pushes. Binds the PR thread to this ticket. Returns published: false, pushing nothing, when the agent account has no write access to the repository. Returns published: false with review_required, pushing nothing, when the host requires a review first: run the superagent-reviewer subagent, then publish again.",
+			description: "Push this ticket's commits and open its pull request, or reuse the open one for the branch; never force-pushes. Binds the PR thread to this ticket. Returns published: false, pushing nothing, when the agent account has no write access to the repository. Returns published: false with review_required, pushing nothing, when the host requires a review first: run the superagent-reviewer subagent, then publish again. Returns published: false, pushing nothing, when the configured target branch is missing on the remote.",
 			schema: z.object({
 				title: z.string().trim().min(1).max(256),
 				body: z.string().trim().min(1).max(6e4),
@@ -9122,6 +9253,12 @@ function deliveryTools(host, ticketId) {
 				try {
 					pushed = await deliveryHost().push(ticketId, { coAuthors: args.coAuthors });
 				} catch (error) {
+					if (error instanceof WorkspaceBlocked) return {
+						published: false,
+						repository,
+						reason: error.message,
+						next: "Report blocked with the reason; a person must create the branch or fix the repository config"
+					};
 					throw error instanceof RepositoryAccessError ? accessFailure(repository, error) : error;
 				}
 				let pr;
@@ -10736,7 +10873,7 @@ var Runtime = class {
 				});
 			};
 			const deps = {
-				prepare: (ticket) => this.workspaces.prepare(ticket, worktreeName(ticket)),
+				prepare: (ticket) => this.workspaces.prepare(ticket, worktreeName(ticket), branchesOf(this.current, repositoryOf(ticket))),
 				instructions: async (ticket) => this.prompts.instructions("worker", [{
 					source: "ticket-title",
 					text: ticket.title
@@ -11174,6 +11311,8 @@ var Runtime = class {
 		const effective = {
 			...this.current,
 			repositories: next.repositories,
+			branches: next.branches,
+			review: next.review,
 			policy: next.policy,
 			network: next.network,
 			retention: next.retention,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superagent-claude",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "A proactive agent for GitHub repositories. Powered by Claude.",
   "license": "MIT",
   "repository": {