@open330/oac 2026.221.2 → 2026.222.2

package/README.md

@@ -17,12 +17,22 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178C6?logo=typescript&logoColor=white)](https://typescriptlang.org/)
 
-[Getting Started](#-getting-started) · [How It Works](#-how-it-works) · [Commands](#commands) · [Configuration](#configuration) · [Architecture](#architecture) · [Contributing](#contributing)
+[Getting Started](#-getting-started) · [How It Works](#-how-it-works) · [Commands](#commands) · [Configuration](#configuration) · [Concurrency & Multi-User Safety](#concurrency--multi-user-safety) · [For Maintainers](#for-maintainers-target-repos) · [Architecture](#architecture) · [Contributing](#contributing)
 
 </div>
 
 ---
 
+<div><img src="https://quickstart-for-agents.vercel.app/api/header.svg?theme=opencode&logo=OAC&title=Use+leftover+AI+tokens+to+auto-contribute+to+open+source+repos&font=inter" width="100%" /></div>
+
+```
+You are an AI agent working on Open Agent Contribution (OAC), a CLI tool that
+uses spare AI agent tokens to automatically scan repos, discover tasks, and
+submit pull requests via Claude Code or Codex.
+Clone https://github.com/Open330/open-agent-contribution and help improve
+scanners, execution pipelines, or add new agent provider adapters.
+```
+
 ## The Problem
 
 You pay for AI agent tokens every month. Claude Code, Codex, OpenCode — they all come with token budgets. But most days, you don't use them all. Those leftover tokens? **Wasted.**
@@ -276,6 +286,165 @@ export default defineConfig({
 
 ---
 
+## Concurrency & Multi-User Safety
+
+When multiple OAC instances run against the same repository simultaneously (e.g., several team members running `oac run` at the same time), there is a risk of duplicate PRs targeting the same issue. OAC prevents this with a **2-layer guard system** that checks for existing OAC pull requests at two critical points in the pipeline.
+
+```
+  Instance A                          Instance B
+  ─────────                           ─────────
+  oac run                             oac run
+      │                                   │
+      ▼                                   ▼
+  ┌──────────────┐                   ┌──────────────┐
+  │  Layer 1     │                   │  Layer 1     │
+  │  Discovery   │ ◄── Both scan ──►│  Discovery   │
+  │  PR check    │     GitHub PRs    │  PR check    │
+  └──────┬───────┘                   └──────┬───────┘
+         │                                  │
+    Issue #42 not                      Issue #42 not
+    claimed → keep                     claimed → keep
+         │                                  │
+         ▼                                  ▼
+    (analyze, plan,                    (analyze, plan,
+     execute...)                        execute...)
+         │                                  │
+         ▼                                  ▼
+  ┌──────────────┐                   ┌──────────────┐
+  │  Layer 3     │                   │  Layer 3     │
+  │  Pre-PR      │                   │  Pre-PR      │
+  │  guard       │                   │  guard       │
+  └──────┬───────┘                   └──────┬───────┘
+         │                                  │
+    No OAC PR yet                     Instance A's PR
+    → create PR ✔                     now exists → skip ✘
+```
+
+### Layer 1: Discovery-Time Filtering
+
+During task discovery, the GitHub Issues scanner fetches all open PRs whose title starts with `[OAC]` and extracts the issue numbers they reference (via `Fixes #N`, `Closes #N`, or `Resolves #N` in the PR body). Any issue that already has a matching OAC PR is filtered out of the task list entirely — the agent never even attempts work on it.
+
+- **When:** Runs at the start of every `oac run`, during the scan phase
+- **Effect:** Issues with existing OAC PRs are excluded from the task list
+- **Failure mode:** Fail-open — if the GitHub API is unreachable, no issues are filtered out and the pipeline continues normally
+
+### Layer 3: Pre-PR Guard
+
+Even after Layer 1, a race condition is possible: two instances might discover the same issue before either has created a PR. Layer 3 closes this gap by performing a second check immediately before pushing the branch and creating the PR. If another OAC PR for the same issue now exists, the PR creation is skipped.
+
+- **When:** Runs after code execution and diff validation, just before `git push` and PR creation
+- **Effect:** Skips PR creation if a duplicate OAC PR is detected, avoiding wasted pushes
+- **Failure mode:** Fail-open — if the check fails, the PR is created anyway (better to create a possible duplicate than to silently discard completed work)
+
+### How OAC PRs Are Identified
+
+Both layers use the same detection logic:
+1. Fetch up to 100 most recently updated open PRs from the target repository
+2. Filter to PRs whose title starts with **`[OAC]`**
+3. Scan the PR body for **`Fixes #N`**, **`Closes #N`**, or **`Resolves #N`**
+4. Match the extracted issue number against the current task's linked issue
+
+### Best Practices for Teams
+
+- **No configuration needed.** The guards are always active — there is nothing to enable or disable.
+- **Stagger start times slightly** (even 30 seconds apart) to give Layer 1 the best chance of catching duplicates before any work begins.
+- **Use a shared config** (`oac.config.ts`) with the same `issueLabels` filter so all instances target the same pool of issues and the guards can detect overlaps.
+- **Check `oac log`** after runs to see if any tasks were skipped due to duplicate detection.
+- **Don't worry about edge cases.** Both layers are fail-open by design — in the worst case, a duplicate PR is created, which is easy to close manually. No work is ever silently lost.
+
+---
+
+## For Maintainers (Target Repos)
+
+If you are the repository owner receiving OAC contributions, treat contribution rules as
+**repository-owned policy** (in the target repo), not contributor-local config.
+
+### Ownership Model
+
+- **Target repo owns scope and rules**: keep allowed areas, constraints, and acceptance criteria in the target repository.
+- **Contributors own runtime choices**: provider, token budget, and local execution environment stay in each contributor's `oac.config.ts`.
+- **Why this split works**: maintainers can evolve policy in git history, reviewers can audit intent, and contributors cannot silently bypass project rules.
+
+### Recommended Structure (in the target repo)
+
+```text
+.context/
+  plans/
+    README.md                 # contribution policy and workflow
+    ISSUE-123.md              # task-specific plan (one issue = one plan)
+    ISSUE-456.md
+```
+
+### Plan Template (`.context/plans/ISSUE-123.md`)
+
+```markdown
+# ISSUE-123 - Improve contribution intake
+
+## Scope
+- Allowed paths: `src/discovery/**`, `README.md`
+- Forbidden paths: `package.json`, `.github/workflows/**`
+
+## Must
+- Keep backward compatibility for existing config keys
+- Add/adjust tests for changed behavior
+- Keep PR title format: `[OAC] ...`
+
+## Must Not
+- No breaking CLI flag changes
+- No unrelated refactors
+
+## Acceptance Criteria
+- `pnpm lint`, `pnpm typecheck`, `pnpm test` all pass
+- PR body links this issue and summarizes user impact
+- Reviewer can validate behavior with one command sequence
+
+## Notes for Agent
+- Prefer minimal, surgical changes
+- If ambiguous, choose the safest non-breaking path
+```
+
+### Add a Maintainer Section to Your Target Repo README
+
+Use this snippet in repos that want to receive OAC contributions:
+
+````markdown
+## AI Contribution Policy (OAC)
+
+This repository accepts contributions generated by Open Agent Contribution (OAC).
+
+- Before running OAC, read `.context/plans/README.md` and the relevant `ISSUE-*.md` plan.
+- Work outside allowed paths will be rejected in review.
+- PRs must include issue linkage and pass lint/typecheck/tests.
+
+Recommended command:
+
+```bash
+oac run --repo <owner/repo>
+```
+````
+
+### Systematic Intake Workflow
+
+1. **Maintainer prepares issues**
+   - Create actionable issues and add labels such as `oac-ready`, `documentation`, `good-first-issue`.
+   - Add or update `.context/plans/ISSUE-<number>.md` for each issue you want agents to pick up.
+2. **Contributor scopes discovery**
+   - In contributor `oac.config.ts`, set `discovery.issueLabels` to maintainer labels (for example, `"oac-ready"`).
+3. **OAC executes with duplicate guards**
+   - Layer 1 + Layer 3 prevent most duplicate PRs across concurrent contributors.
+4. **Maintainer reviews against plan**
+   - Check diff vs `Scope`, `Must`, `Must Not`, and acceptance criteria in the issue plan document.
+
+### Current Behavior Note
+
+Today, OAC does not hard-fail when `.context/plans/*` is missing. The recommended production pattern is:
+
+- maintain plan documents in the target repo,
+- require issue/PR linkage,
+- and enforce policy at review or CI level.
+
+---
+
 ## Architecture
 
 ```

package/dist/budget/index.js

@@ -8,7 +8,7 @@ import {
   estimateLocChanges,
   estimateTokens,
   resetCounters
-} from "../chunk-5GAUWC3L.js";
+} from "../chunk-ALBVUNUY.js";
 export {
   ClaudeTokenCounter,
   CodexTokenCounter,

package/dist/{chunk-EYUQMPVO.js → chunk-27FEE5KS.js}

@@ -1,10 +1,10 @@
 import {
   OacError,
   executionError
-} from "./chunk-7C7SC4TZ.js";
+} from "./chunk-I3TKNT4M.js";
 import {
   isRecord
-} from "./chunk-6A37SKAJ.js";
+} from "./chunk-JDFAJP45.js";
 
 // src/execution/agents/claude-code.adapter.ts
 import { createInterface } from "readline";
@@ -126,11 +126,18 @@ function patchTokenState(state, patch) {
   };
 }
 function parseTokenPatchFromPayload(payload) {
-  const usage = isRecord(payload.usage) ? payload.usage : void 0;
+  const message = isRecord(payload.message) ? payload.message : void 0;
+  const usage = isRecord(payload.usage) ? payload.usage : isRecord(message?.usage) ? message.usage : void 0;
+  const baseInput = readNumber(
+    payload.inputTokens ?? payload.input_tokens ?? payload.promptTokens ?? payload.prompt_tokens ?? usage?.inputTokens ?? usage?.input_tokens ?? usage?.promptTokens ?? usage?.prompt_tokens
+  );
+  const cacheRead = readNumber(usage?.cache_read_input_tokens ?? usage?.cacheReadInputTokens);
+  const cacheCreate = readNumber(
+    usage?.cache_creation_input_tokens ?? usage?.cacheCreationInputTokens
+  );
+  const effectiveInput = baseInput !== void 0 ? (baseInput ?? 0) + (cacheRead ?? 0) + (cacheCreate ?? 0) : void 0;
   return {
-    inputTokens: readNumber(
-      payload.inputTokens ?? payload.input_tokens ?? payload.promptTokens ?? payload.prompt_tokens ?? usage?.inputTokens ?? usage?.input_tokens ?? usage?.promptTokens ?? usage?.prompt_tokens
-    ),
+    inputTokens: effectiveInput,
     outputTokens: readNumber(
       payload.outputTokens ?? payload.output_tokens ?? payload.completionTokens ?? payload.completion_tokens ?? usage?.outputTokens ?? usage?.output_tokens ?? usage?.completionTokens ?? usage?.completion_tokens
     ),
@@ -313,7 +320,7 @@ var ClaudeCodeAdapter = class {
   runningExecutions = /* @__PURE__ */ new Map();
   async checkAvailability() {
     try {
-      const result = await execa("claude", ["--version"], { reject: false });
+      const result = await execa("claude", ["--version"], { reject: false, stdin: "ignore" });
       const version = result.stdout.trim().split("\n")[0];
       if (result.exitCode === 0) {
         return {
@@ -353,14 +360,25 @@ var ClaudeCodeAdapter = class {
       OAC_TOKEN_BUDGET: `${params.tokenBudget}`,
       OAC_ALLOW_COMMITS: `${params.allowCommits}`
     };
-    const subprocess = execa("claude", ["-p", params.prompt], {
-      cwd: params.workingDirectory,
-      env: processEnv,
-      extendEnv: false,
-      reject: false,
-      timeout: params.timeoutMs,
-      stdin: "ignore"
-    });
+    const subprocess = execa(
+      "claude",
+      [
+        "-p",
+        "--dangerously-skip-permissions",
+        "--verbose",
+        "--output-format",
+        "stream-json",
+        params.prompt
+      ],
+      {
+        cwd: params.workingDirectory,
+        env: processEnv,
+        extendEnv: false,
+        reject: false,
+        timeout: params.timeoutMs,
+        stdin: "ignore"
+      }
+    );
     this.runningExecutions.set(params.executionId, subprocess);
     const consumeStream = async (stream, streamName) => {
       if (!stream) {
@@ -1065,10 +1083,14 @@ function normalizeUnknownError3(error, executionId) {
     });
   }
   if (/rate.limit|429|too many requests|throttl/i.test(message)) {
-    return executionError("AGENT_RATE_LIMITED", `OpenCode execution rate-limited for ${executionId}`, {
-      context: { executionId, message },
-      cause: error
-    });
+    return executionError(
+      "AGENT_RATE_LIMITED",
+      `OpenCode execution rate-limited for ${executionId}`,
+      {
+        context: { executionId, message },
+        cause: error
+      }
+    );
   }
   if (/network|ECONN|ENOTFOUND|EAI_AGAIN/i.test(message)) {
     return new OacError(
@@ -1159,17 +1181,13 @@ var OpenCodeAdapter = class {
       OAC_TOKEN_BUDGET: `${params.tokenBudget}`,
       OAC_ALLOW_COMMITS: `${params.allowCommits}`
     };
-    const subprocess = execa3(
-      "opencode",
-      ["run", "--format", "json", params.prompt],
-      {
-        cwd: params.workingDirectory,
-        env: processEnv,
-        reject: false,
-        timeout: params.timeoutMs,
-        stdin: "ignore"
-      }
-    );
+    const subprocess = execa3("opencode", ["run", "--format", "json", params.prompt], {
+      cwd: params.workingDirectory,
+      env: processEnv,
+      reject: false,
+      timeout: params.timeoutMs,
+      stdin: "ignore"
+    });
     this.runningExecutions.set(params.executionId, subprocess);
     const processStdoutLine = (line) => {
       const payload = parseJsonPayload3(line);
@@ -1304,9 +1322,7 @@ var OpenCodeAdapter = class {
 var AdapterRegistry = class {
   factories = /* @__PURE__ */ new Map();
   /** Well-known aliases (e.g. legacy IDs) that map to canonical provider IDs. */
-  aliases = /* @__PURE__ */ new Map([
-    ["codex-cli", "codex"]
-  ]);
+  aliases = /* @__PURE__ */ new Map([["codex-cli", "codex"]]);
   /** Register a new adapter factory. Replaces any previous factory for the same ID. */
   register(id, factory) {
     this.factories.set(id, factory);
@@ -1466,8 +1482,27 @@ function readPositiveNumber(value) {
 function readMetadataNumber(task, key) {
   return readPositiveNumber(task.metadata[key]);
 }
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function readContextAck(task) {
+  const raw = task.metadata.contextAck;
+  if (!isRecord2(raw)) {
+    return void 0;
+  }
+  const files = Array.isArray(raw.files) ? raw.files.filter((item) => typeof item === "string" && item.trim().length > 0) : [];
+  const summary = Array.isArray(raw.summary) ? raw.summary.filter(
+    (item) => typeof item === "string" && item.trim().length > 0
+  ) : [];
+  const digest = typeof raw.digest === "string" && raw.digest.trim().length > 0 ? raw.digest : void 0;
+  if (files.length === 0) {
+    return void 0;
+  }
+  return { files, summary, digest };
+}
 function buildTaskPrompt(task) {
   const fileList = task.targetFiles.length > 0 ? task.targetFiles.join("\n") : "(none provided)";
+  const contextAck = readContextAck(task);
   const lines = [
     "You are implementing a scoped repository contribution task.",
     `Task ID: ${task.id}`,
@@ -1495,6 +1530,23 @@ function buildTaskPrompt(task) {
     "",
     "Apply minimal, safe changes and ensure the repository remains buildable."
   );
+  if (contextAck) {
+    lines.push(
+      "",
+      "Repository contribution policy (MUST FOLLOW):",
+      ...contextAck.files.map((file) => `- ${file}`)
+    );
+    if (contextAck.summary.length > 0) {
+      lines.push("", "Policy summary:", ...contextAck.summary.map((item) => `- ${item}`));
+    }
+    if (contextAck.digest) {
+      lines.push("", `Context digest: ${contextAck.digest}`);
+    }
+    lines.push(
+      "",
+      "Treat these policy files as authoritative. Stay within scope and satisfy all Must/Must Not constraints."
+    );
+  }
   return lines.filter((l) => l !== void 0).join("\n");
 }
 function stageFromEvent(event) {
@@ -1877,4 +1929,4 @@ export {
   isTransientError,
   ExecutionEngine
 };
-//# sourceMappingURL=chunk-EYUQMPVO.js.map
+//# sourceMappingURL=chunk-27FEE5KS.js.map