@vicfei/dsh-super-agent 0.0.0-stage → 0.5.1

package/dist/executor.d.ts

@@ -0,0 +1,43 @@
+export interface ExecutorConfig {
+    /** Shell command (sh -c). Env: DSH_DIR, DSH_PROMPT_FILE, DSH_TICKET, DSH_THREAD, DSH_REPO, DSH_AUTHOR. */
+    command: string;
+    /** Local clone to prepare worktrees from. */
+    repoDir: string;
+    /** Worktrees live here (suggested .state/work). */
+    workRoot: string;
+    /** Prepare command template with {dir} and {branch}; default uses git worktree add. */
+    prepare?: string;
+    /** Background cap (docs/003: at most 30 minutes). */
+    timeoutMs: number;
+    /** Worker slots per run. */
+    maxWorkers: number;
+    /** Substrings that refuse execution — "fail when invoked by name". */
+    blockedCommands: string[];
+}
+export interface ExecutorResult {
+    exitCode: number | null;
+    timedOut: boolean;
+    output: string;
+    worktree: string;
+    /** Commit the worktree branch was created from — the base for PR delivery diffing. */
+    baseSha: string;
+}
+export declare class Executor {
+    readonly cfg: ExecutorConfig;
+    constructor(cfg: ExecutorConfig);
+    /** Throws on blocked command, prepare failure, or unusable config — the caller records failure. */
+    run(ticket: {
+        id: number;
+        threadId: string;
+    }, trigger: {
+        body: string;
+        author: string;
+    }, repo: string): Promise<ExecutorResult>;
+}
+export declare function renderPrompt(ticket: {
+    id: number;
+    threadId: string;
+}, trigger: {
+    body: string;
+    author: string;
+}, repo: string): string;

package/dist/executor.js

@@ -0,0 +1,100 @@
+// Executor — a ticket's work runs in a subprocess in its own git worktree, following
+// dsh-superagent-prototype docs/003: per-ticket Executor directory (git worktree), prepare once,
+// background cap enforced by timeout+kill, blocked commands fail by name.
+// Any CLI counts as the worker: the command string sees only env vars, never credentials.
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+const OUTPUT_CAP = 64 * 1024;
+function sh(cmd, opts) {
+    return new Promise((resolve) => {
+        // detached ⇒ own process group, so a timeout can kill the whole tree — killing only the
+        // shell leaves grandchildren holding the stdio pipes (and the promise pending).
+        const child = spawn("/bin/sh", ["-c", cmd], { cwd: opts.cwd, env: { ...process.env, ...opts.env }, detached: true });
+        let out = "";
+        const onData = (d) => {
+            if (out.length < OUTPUT_CAP)
+                out += d.toString("utf8");
+        };
+        child.stdout.on("data", onData);
+        child.stderr.on("data", onData);
+        const timer = setTimeout(() => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, "SIGKILL");
+            }
+            catch { /* already gone */ }
+        }, opts.timeoutMs);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, output: out });
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: null, output: `${out}\n${err.message}` });
+        });
+    });
+}
+export class Executor {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** Throws on blocked command, prepare failure, or unusable config — the caller records failure. */
+    async run(ticket, trigger, repo) {
+        const blocked = this.cfg.blockedCommands.find((b) => this.cfg.command.includes(b));
+        if (blocked)
+            throw new Error(`executor command blocked by name: ${blocked}`);
+        // Absolute paths: the child runs with cwd = worktree, so a relative DSH_DIR/repoDir would
+        // resolve against the wrong directory.
+        const dir = resolve(join(this.cfg.workRoot, `ticket-${ticket.id}`));
+        const branch = `dsh/ticket-${ticket.id}`;
+        const repoDir = resolve(this.cfg.repoDir);
+        mkdirSync(dir, { recursive: true });
+        // -B makes re-running a resumed ticket idempotent (branch reset instead of "already exists").
+        const prepare = this.cfg.prepare ?? `git worktree add -B {branch} {dir}`;
+        const prep = await sh(prepare.replaceAll("{dir}", JSON.stringify(dir)).replaceAll("{branch}", branch), {
+            cwd: repoDir,
+            timeoutMs: 10 * 60 * 1000, // prepare gets ten minutes (docs/003)
+        });
+        if (prep.code !== 0)
+            throw new Error(`prepare failed (exit ${prep.code}): ${prep.output.trim().slice(0, 300)}`);
+        const promptFile = join(dir, "DSH_PROMPT.md");
+        writeFileSync(promptFile, renderPrompt(ticket, trigger, repo));
+        const baseSha = (await sh(`git -C ${JSON.stringify(dir)} rev-parse HEAD`, { timeoutMs: 10_000 })).output.trim();
+        const run = await sh(this.cfg.command, {
+            cwd: dir,
+            timeoutMs: this.cfg.timeoutMs,
+            env: {
+                DSH_DIR: dir,
+                DSH_PROMPT_FILE: promptFile,
+                DSH_TICKET: String(ticket.id),
+                DSH_THREAD: ticket.threadId,
+                DSH_REPO: repo,
+                DSH_AUTHOR: trigger.author,
+            },
+        });
+        const timedOut = run.code === null;
+        return { exitCode: run.code, timedOut, output: run.output, worktree: dir, baseSha };
+    }
+}
+export function renderPrompt(ticket, trigger, repo) {
+    return [
+        `# Ticket #${ticket.id}`,
+        "",
+        `Author: @${trigger.author}`,
+        `Thread: ${ticket.threadId}`,
+        `Repository: ${repo}`,
+        "",
+        "## Request",
+        "",
+        trigger.body.trim() || "(no body)",
+        "",
+        "## Rules",
+        "",
+        "- Do the requested work inside this directory (a git worktree of the repository).",
+        "- Your stdout is posted to the thread as the report — end it with a concise summary (≤150 words).",
+        "- If the request is beyond what you can do here, say so plainly in the summary instead of improvising.",
+    ].join("\n");
+}
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"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"}

package/dist/gate.d.ts

@@ -0,0 +1,34 @@
+import type { Policy, Strength, Trigger } from "./domain.js";
+export type GateResult = {
+    strength: Strength;
+    basis: string;
+} | {
+    strength: null;
+    basis: string;
+};
+/** A listed bot can produce an inferred candidate, never an explicit request. */
+export declare function evaluateGate(policy: Policy, trigger: Trigger): GateResult;
+export type Assessment = "positive" | "negative";
+export type Resolution = {
+    action: "accept";
+    strength: Strength;
+    basis: string;
+}
+/** observe mode: recorded, nothing accepted. */
+ | {
+    action: "shadow";
+    strength: "inferred";
+    basis: string;
+    wouldAccept: true;
+} | {
+    action: "reject";
+    basis: string;
+};
+/**
+ * Resolve a gated Trigger under the Policy's accept mode.
+ * Invariants (docs/002):
+ *   - explicit requests work in every mode;
+ *   - nothing inferred becomes a candidate while mode is off;
+ *   - accepting an inferred candidate always requires an assessment.
+ */
+export declare function resolveCandidate(policy: Policy, gate: GateResult, assessment: Assessment | undefined): Resolution;

package/dist/gate.js

@@ -0,0 +1,66 @@
+// Host-enforced admission gate — adapted from dsh-superagent-prototype docs/002 (MIT, DeepSeek).
+// The gate is deterministic (Fast Path): sender + scope + addressing checked against the Policy's
+// admission table. LLM assessment (Slow Path) only ever sees candidates that survive here, and
+// only for inferred strength — natural language can never turn an ignore into an admit.
+const lc = (s) => s.toLowerCase();
+/** Missing scope rows fail closed: every cell ignore. */
+function rowOf(policy, trigger) {
+    const closed = { scope: trigger.scope, listedNotAddressing: "ignore", unlistedAddressing: "ignore", unlistedNotAddressing: "ignore" };
+    return policy.table.find((r) => r.scope === trigger.scope) ?? closed;
+}
+/** A listed bot can produce an inferred candidate, never an explicit request. */
+export function evaluateGate(policy, trigger) {
+    const row = rowOf(policy, trigger);
+    const listed = policy.allowedList.map(lc).includes(lc(trigger.author.login));
+    const knownBot = trigger.author.isBot || policy.botList.map(lc).includes(lc(trigger.author.login));
+    if (knownBot) {
+        // Bots are checked against the bot list, not the allowed list; ceiling is "inferred".
+        if (trigger.addressing)
+            return { strength: "inferred", basis: `bot ${trigger.author.login} addressing agent` };
+        const cell = row.unlistedNotAddressing; // bots never count as "listed" senders
+        return cell === "inferred"
+            ? { strength: "inferred", basis: `bot ${trigger.author.login} in receive-all scope` }
+            : { strength: null, basis: `bot ${trigger.author.login} not admitted by cell` };
+    }
+    if (listed) {
+        if (trigger.addressing)
+            return { strength: "explicit", basis: `allowed ${trigger.author.login} addressing agent` };
+        return row.listedNotAddressing === "inferred"
+            ? { strength: "inferred", basis: `allowed ${trigger.author.login} not addressing` }
+            : { strength: null, basis: `allowed ${trigger.author.login} ignored by cell` };
+    }
+    const cell = trigger.addressing ? row.unlistedAddressing : row.unlistedNotAddressing;
+    return cell === "inferred"
+        ? { strength: "inferred", basis: `unlisted ${trigger.author.login} admitted by cell` }
+        : { strength: null, basis: `unlisted ${trigger.author.login} not admitted by cell` };
+}
+/**
+ * Resolve a gated Trigger under the Policy's accept mode.
+ * Invariants (docs/002):
+ *   - explicit requests work in every mode;
+ *   - nothing inferred becomes a candidate while mode is off;
+ *   - accepting an inferred candidate always requires an assessment.
+ */
+export function resolveCandidate(policy, gate, assessment) {
+    if (gate.strength === null)
+        return { action: "reject", basis: gate.basis };
+    if (gate.strength === "explicit") {
+        // Explicit admission never waits on an assessment or a mode.
+        return { action: "accept", strength: "explicit", basis: gate.basis };
+    }
+    if (assessment === undefined) {
+        throw new Error("inferred candidate cannot be resolved without an assessment (direct accept refused)");
+    }
+    if (assessment === "negative") {
+        return { action: "reject", basis: `inferred candidate assessed negative (${gate.basis})` };
+    }
+    switch (policy.acceptMode) {
+        case "off":
+            return { action: "reject", basis: "inferred strength has no effect while acceptMode is off" };
+        case "observe":
+            return { action: "shadow", strength: "inferred", basis: gate.basis, wouldAccept: true };
+        case "auto":
+            return { action: "accept", strength: "inferred", basis: gate.basis };
+    }
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"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"}

package/dist/github/client.d.ts

@@ -0,0 +1,63 @@
+export interface GhActor {
+    login: string;
+    type: string;
+}
+interface GhItemBase {
+    id: number;
+    user: GhActor | null;
+    body: string | null;
+    created_at: string;
+}
+export interface GhIssue extends GhItemBase {
+    number: number;
+    title: string | null;
+    /** Present ⇒ this entry is a PR that leaked into the issues feed. */
+    pull_request?: unknown;
+}
+export interface GhIssueComment extends GhItemBase {
+    /** api url of the parent issue (issues or PR conversation). */
+    issue_url: string;
+}
+export interface GhPull extends GhItemBase {
+    number: number;
+    title: string | null;
+}
+export interface GhReviewComment extends GhItemBase {
+    /** api url of the parent pull. */
+    pull_request_url: string;
+    in_reply_to_id?: number;
+}
+export declare class GitHubClient {
+    private readonly fetchImpl;
+    private readonly apiBase;
+    constructor(opts?: {
+        token?: string;
+        fetchImpl?: typeof fetch;
+        apiBase?: string;
+    });
+    private readonly token;
+    private request;
+    /** Newest-first single page. Filtering by read position happens in the Source. */
+    private list;
+    listIssues(repo: string): Promise<GhIssue[]>;
+    listIssueComments(repo: string): Promise<GhIssueComment[]>;
+    listPulls(repo: string): Promise<GhPull[]>;
+    listReviewComments(repo: string): Promise<GhReviewComment[]>;
+    /** Delivery: write into the originating thread. */
+    postIssueComment(repo: string, issueNumber: number, body: string): Promise<{
+        id: number;
+    }>;
+    private defaultBranchCache;
+    getDefaultBranch(repo: string): Promise<string>;
+    /** Delivery: turn a pushed ticket branch into a pull request. */
+    createPullRequest(repo: string, pr: {
+        title: string;
+        head: string;
+        base: string;
+        body: string;
+    }): Promise<{
+        number: number;
+        html_url: string;
+    }>;
+}
+export {};

package/dist/github/client.js

@@ -0,0 +1,71 @@
+// GitHub REST client — thin, injectable fetch, credentials never persisted.
+// v0 uses a PAT and polling; a GitHub App is a later Source-kind config, not a code path.
+export class GitHubClient {
+    fetchImpl;
+    apiBase;
+    constructor(opts = {}) {
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.apiBase = opts.apiBase ?? "https://api.github.com";
+        this.token = opts.token ?? "";
+    }
+    token;
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.apiBase}${path}`, {
+            method,
+            headers: {
+                accept: "application/vnd.github+json",
+                "x-github-api-version": "2022-11-28",
+                ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            // The three failures a fresh install hits; the raw body alone is cryptic (M5-5).
+            const hint = res.status === 401
+                ? " — GITHUB_TOKEN was rejected: check its value / expiry"
+                : res.status === 403 && /rate limit/i.test(text)
+                    ? " — rate limited: set GITHUB_TOKEN to raise the limit"
+                    : res.status === 403
+                        ? " — forbidden: the token may lack access to this repo"
+                        : "";
+            throw new Error(`GitHub API ${method} ${path} → ${res.status}: ${text.slice(0, 200)}${hint}`);
+        }
+        return (await res.json());
+    }
+    /** Newest-first single page. Filtering by read position happens in the Source. */
+    list(repo, path) {
+        return this.request("GET", `/repos/${repo}${path}?state=all&sort=created&direction=desc&per_page=50`);
+    }
+    listIssues(repo) {
+        return this.list(repo, "/issues");
+    }
+    listIssueComments(repo) {
+        return this.list(repo, "/issues/comments");
+    }
+    listPulls(repo) {
+        return this.list(repo, "/pulls");
+    }
+    listReviewComments(repo) {
+        return this.list(repo, "/pulls/comments");
+    }
+    /** Delivery: write into the originating thread. */
+    postIssueComment(repo, issueNumber, body) {
+        return this.request("POST", `/repos/${repo}/issues/${issueNumber}/comments`, { body });
+    }
+    defaultBranchCache = new Map();
+    async getDefaultBranch(repo) {
+        const cached = this.defaultBranchCache.get(repo);
+        if (cached)
+            return cached;
+        const data = await this.request("GET", `/repos/${repo}`);
+        this.defaultBranchCache.set(repo, data.default_branch);
+        return data.default_branch;
+    }
+    /** Delivery: turn a pushed ticket branch into a pull request. */
+    createPullRequest(repo, pr) {
+        return this.request("POST", `/repos/${repo}/pulls`, pr);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/github/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/github/client.ts"],"names":[],"mappings":"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"}

package/dist/github/source.d.ts

@@ -0,0 +1,33 @@
+import type { Trigger } from "../domain.js";
+import { GitHubClient } from "./client.js";
+import type { SourceState, StateStore } from "./state.js";
+export interface GitHubSourceOptions {
+    /** owner/repo */
+    repo: string;
+    /** The agent's own login — addressing is an @mention of it (case-insensitive). */
+    agentLogin: string;
+    client: GitHubClient;
+    /** Required only for poll(); collect() is stateless. */
+    state?: StateStore;
+}
+/** True for App accounts and `[bot]` logins — bots cap at inferred strength in the gate. */
+export declare function isBotActor(login: string, type: string): boolean;
+export declare class GitHubSource {
+    private readonly opts;
+    constructor(opts: GitHubSourceOptions);
+    /**
+     * Pure collection: compute triggers newer than `from` and the next state, persisting nothing.
+     * The Engine ingests triggers + positions in one transaction (exactly-once); poll() is the
+     * file-backed convenience wrapper kept for standalone use. `exclude` drops the agent's own
+     * posted comments (docs/001: a Source "filters its own messages").
+     */
+    collect(from: SourceState, opts?: {
+        exclude?: ReadonlySet<string>;
+    }): Promise<{
+        triggers: Trigger[];
+        next: SourceState;
+    }>;
+    /** File-backed wrapper: collect + persist positions (at-most-once across a crash). */
+    poll(): Promise<Trigger[]>;
+    private toTrigger;
+}

package/dist/github/source.js

@@ -0,0 +1,110 @@
+// GitHub Source — turns repo events into domain Triggers (docs/001: "A Source produces Triggers").
+// Four feeds polled newest-first; an item is new iff its id exceeds the feed's read position.
+// PRs leak into the issues listing (same id space) and are skipped there — the pulls feed owns them.
+const SCOPE_OF_FEED = {
+    issue: "issue",
+    issue_comment: "issue_comment",
+    pr: "pr",
+    review_comment: "review_comment",
+};
+/** True for App accounts and `[bot]` logins — bots cap at inferred strength in the gate. */
+export function isBotActor(login, type) {
+    return type === "Bot" || login.endsWith("[bot]");
+}
+function issueNumberFromUrl(url) {
+    const m = url.match(/\/(?:issues|pulls)\/(\d+)$/);
+    return m ? m[1] : "unknown";
+}
+export class GitHubSource {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Pure collection: compute triggers newer than `from` and the next state, persisting nothing.
+     * The Engine ingests triggers + positions in one transaction (exactly-once); poll() is the
+     * file-backed convenience wrapper kept for standalone use. `exclude` drops the agent's own
+     * posted comments (docs/001: a Source "filters its own messages").
+     */
+    async collect(from, opts = {}) {
+        const state = { positions: { ...from.positions } };
+        const out = [];
+        const wanted = (id) => !opts.exclude?.has(id);
+        // Each feed compares against its position AT COLLECT START (frozen) and advances once at the
+        // end — comparing against a mid-loop maximum would swallow older-but-new items (newest-first).
+        const issues = await this.opts.client.listIssues(this.opts.repo);
+        let start = state.positions.issue;
+        let maxSeen = start;
+        for (const it of issues) {
+            if (it.id <= start)
+                break;
+            if (it.pull_request !== undefined)
+                continue; // pulls feed owns PRs
+            if (wanted(`github:issue:${it.id}`))
+                out.push(this.toTrigger("issue", it.id, it.user, it.body, it.created_at, `github:${this.opts.repo}/issues/${it.number}`, SCOPE_OF_FEED.issue));
+            maxSeen = Math.max(maxSeen, it.id);
+        }
+        state.positions.issue = maxSeen;
+        const comments = await this.opts.client.listIssueComments(this.opts.repo);
+        start = state.positions.issue_comment;
+        maxSeen = start;
+        for (const it of comments) {
+            if (it.id <= start)
+                break;
+            const n = issueNumberFromUrl(it.issue_url);
+            if (wanted(`github:issue_comment:${it.id}`))
+                out.push(this.toTrigger("issue_comment", it.id, it.user, it.body, it.created_at, `github:${this.opts.repo}/issues/${n}`, SCOPE_OF_FEED.issue_comment));
+            maxSeen = Math.max(maxSeen, it.id);
+        }
+        state.positions.issue_comment = maxSeen;
+        const pulls = await this.opts.client.listPulls(this.opts.repo);
+        start = state.positions.pr;
+        maxSeen = start;
+        for (const it of pulls) {
+            if (it.id <= start)
+                break;
+            if (wanted(`github:pr:${it.id}`))
+                out.push(this.toTrigger("pr", it.id, it.user, it.body, it.created_at, `github:${this.opts.repo}/pulls/${it.number}`, SCOPE_OF_FEED.pr));
+            maxSeen = Math.max(maxSeen, it.id);
+        }
+        state.positions.pr = maxSeen;
+        const reviews = await this.opts.client.listReviewComments(this.opts.repo);
+        start = state.positions.review_comment;
+        maxSeen = start;
+        for (const it of reviews) {
+            if (it.id <= start)
+                break;
+            const n = issueNumberFromUrl(it.pull_request_url);
+            if (wanted(`github:review_comment:${it.id}`))
+                out.push(this.toTrigger("review_comment", it.id, it.user, it.body, it.created_at, `github:${this.opts.repo}/pulls/${n}`, SCOPE_OF_FEED.review_comment));
+            maxSeen = Math.max(maxSeen, it.id);
+        }
+        state.positions.review_comment = maxSeen;
+        return { triggers: out, next: state };
+    }
+    /** File-backed wrapper: collect + persist positions (at-most-once across a crash). */
+    async poll() {
+        if (!this.opts.state)
+            throw new Error("poll() requires a StateStore; use collect() otherwise");
+        const from = this.opts.state.load();
+        const { triggers, next } = await this.collect(from);
+        this.opts.state.save(next); // persist before handing out — see state.ts note
+        return triggers;
+    }
+    toTrigger(feed, id, user, body, ts, threadId, scope) {
+        const login = user?.login ?? "ghost";
+        const mention = `@${this.opts.agentLogin.toLowerCase()}`;
+        const addressing = (body ?? "").toLowerCase().includes(mention);
+        return {
+            id: `github:${feed}:${id}`,
+            source: "github",
+            scope,
+            threadId,
+            author: { login, isBot: user ? isBotActor(login, user.type) : true },
+            addressing,
+            body: body ?? "",
+            ts,
+        };
+    }
+}
+//# sourceMappingURL=source.js.map

package/dist/github/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/github/source.ts"],"names":[],"mappings":"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"}

package/dist/github/state.d.ts

@@ -0,0 +1,15 @@
+export type Feed = "issue" | "issue_comment" | "pr" | "review_comment";
+export interface SourceState {
+    /** Max item id already taken per feed; 0 = never polled. Item ids are increasing ints. */
+    positions: Record<Feed, number>;
+}
+export interface StateStore {
+    load(): SourceState;
+    save(state: SourceState): void;
+}
+export declare class FileSourceState implements StateStore {
+    private readonly file;
+    constructor(file: string);
+    load(): SourceState;
+    save(state: SourceState): void;
+}

package/dist/github/state.js

@@ -0,0 +1,29 @@
+// Read position per feed — docs/001: "A Source holds its own read position (a restart must not
+// replay events)". File-backed for milestone 1; milestone 2's Engine moves it into SQLite in the
+// same transaction as the triggers it produced (exactly-once). Until then: positions are persisted
+// before triggers are handed out (at-most-once across a crash, never replay).
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export class FileSourceState {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    load() {
+        const zeros = { issue: 0, issue_comment: 0, pr: 0, review_comment: 0 };
+        try {
+            const raw = JSON.parse(readFileSync(this.file, "utf8"));
+            return { positions: { ...zeros, ...raw.positions } };
+        }
+        catch {
+            return { positions: zeros };
+        }
+    }
+    save(state) {
+        const tmp = join(dirname(this.file), `.${Math.random().toString(36).slice(2)}.tmp`);
+        mkdirSync(dirname(this.file), { recursive: true });
+        writeFileSync(tmp, JSON.stringify(state, null, 2));
+        renameSync(tmp, this.file); // atomic on POSIX
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/github/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/github/state.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,iGAAiG;AACjG,mGAAmG;AACnG,8EAA8E;AAE9E,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAc1C,MAAM,OAAO,eAAe;IACT,IAAI,CAAS;IAE9B,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,IAAI;QACF,MAAM,KAAK,GAAyB,EAAE,KAAK,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC;QAC7F,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;YACvE,OAAO,EAAE,SAAS,EAAE,EAAE,GAAG,KAAK,EAAE,GAAG,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,IAAI,CAAC,KAAkB;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACpF,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACnD,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,kBAAkB;IAChD,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./domain.js";
+export { evaluateGate, resolveCandidate, type GateResult, type Resolution, type Assessment } from "./gate.js";
+export { Engine, type IngestItem, type TicketView, type DecisionView, type IngestReport } from "./engine.js";
+export { GitHubClient } from "./github/client.js";
+export { GitHubSource, isBotActor } from "./github/source.js";
+export { FileSourceState, type StateStore, type SourceState } from "./github/state.js";
+export { Executor, renderPrompt, type ExecutorConfig, type ExecutorResult } from "./executor.js";
+export { runWork, deliverPullRequest, type WorkReport } from "./work.js";
+export { runWatch, type WatchOptions } from "./watch.js";
+export { classify, formatOutcome, type PollOutcome } from "./runner.js";
+export { llmAssessor, stubAssessor, type Assessor } from "./assess.js";
+export { clipReply, wordCount } from "./clip.js";
+export { startPanel } from "./panel.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+// Public API — everything importable for programmatic use.
+// The CLI (`dist/cli.js`, bin `dsh-super-agent`) covers the operational surface.
+export * from "./domain.js";
+export { evaluateGate, resolveCandidate } from "./gate.js";
+export { Engine } from "./engine.js";
+export { GitHubClient } from "./github/client.js";
+export { GitHubSource, isBotActor } from "./github/source.js";
+export { FileSourceState } from "./github/state.js";
+export { Executor, renderPrompt } from "./executor.js";
+export { runWork, deliverPullRequest } from "./work.js";
+export { runWatch } from "./watch.js";
+export { classify, formatOutcome } from "./runner.js";
+export { llmAssessor, stubAssessor } from "./assess.js";
+export { clipReply, wordCount } from "./clip.js";
+export { startPanel } from "./panel.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,iFAAiF;AAEjF,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAqD,MAAM,WAAW,CAAC;AAC9G,OAAO,EAAE,MAAM,EAA0E,MAAM,aAAa,CAAC;AAC7G,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAqC,MAAM,mBAAmB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAA4C,MAAM,eAAe,CAAC;AACjG,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAmB,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAqB,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAoB,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAiB,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}