@hmharness/agent 0.23.46 → 0.23.48

package/dist/capability.js

@@ -10,6 +10,10 @@ const RISK_RULES = [
     { match: /^(harmony_emulator_(create|start|stop|delete))$/, risk: 'high', permissions: ['device.write', 'process.spawn'], network: true, sideEffects: ['device-mutation'] },
     { match: /^(harmony_build|harmony_cjpm_build|harmony_cjpm_test|harmony_lint)$/, risk: 'medium', permissions: ['process.spawn', 'fs.write'], network: true, sideEffects: ['build-artifacts'] },
     { match: /^spawn_agent$/, risk: 'high', permissions: ['agent.spawn'], network: false, sideEffects: ['subagent-run'] },
+    // git forges (GitHub/AtomGit): reads are low; writes mutate remote VCS state
+    // and are ALL approval-gated (needsApproval) like their domain-ops siblings.
+    { match: /^forge_(repo|pr|issue|release)_(create|merge|upload)$|^forge_raw$/, risk: 'high', permissions: ['net.remote', 'fs.read'], network: true, sideEffects: ['remote-vcs'] },
+    { match: /^forge_(repo|pr|issue)_list$|^forge_pr_checks$|^forge_status$/, risk: 'low', permissions: ['net.remote'], network: true, sideEffects: [] },
 ];
 export function manifestFor(tool) {
     const rule = RISK_RULES.find((r) => r.match.test(tool.name));

package/dist/forge.d.ts

@@ -0,0 +1,81 @@
+import type { Tool, ToolResult } from '@hmharness/kernel';
+export type ForgeHost = 'github' | 'atomgit';
+export declare const FORGE_BINS: Record<ForgeHost, string>;
+export declare function installHint(host: ForgeHost): string;
+export declare function loginHint(host: ForgeHost): string;
+/** Shell-quote one argument. Windows: cmd.exe rules (wrap in "...", double
+ *  embedded quotes; a literal % inside quotes still expands — accepted as a
+ *  cmd.exe limitation, forge inputs rarely contain %). POSIX: single quotes
+ *  with the '\'' escape. (Pure, testable.) */
+export declare function quoteArg(s: string, platform?: string): string;
+/** Parse `auth status` text for BOTH CLIs' phrasings:
+ *  gh: "✓ Logged in to github.com account swsgbl (keyring)"
+ *  ag: "✓ Logged in to atomgit.com as demo-user" */
+export declare function parseAuthStatus(text: string): {
+    loggedIn: boolean;
+    user?: string;
+};
+export declare function repoListArgs(host: ForgeHost, owner?: string, page?: number): string[];
+export declare function repoCreateArgs(host: ForgeHost, name: string, visibility: 'public' | 'private', description?: string): string[];
+export declare function prListArgs(host: ForgeHost, repo: string, state?: string): string[];
+export declare function prCreateArgs(host: ForgeHost, repo: string, head: string, base: string, title: string, body?: string): string[];
+export declare function prMergeArgs(host: ForgeHost, repo: string, num: string, method?: 'merge' | 'squash' | 'rebase'): string[];
+export declare function prChecksArgs(host: ForgeHost, repo: string, num: string): string[];
+export declare function issueListArgs(host: ForgeHost, repo: string, state?: string): string[];
+export declare function issueCreateArgs(host: ForgeHost, repo: string, title: string, body?: string): string[];
+export declare function releaseCreateArgs(host: ForgeHost, repo: string, tag: string, name: string, body: string, target?: string): string[];
+export declare function releaseUploadArgs(host: ForgeHost, repo: string, tag: string, file: string): string[];
+export interface ForgeHostStatus {
+    host: ForgeHost;
+    bin: string;
+    installed: boolean;
+    loggedIn: boolean;
+    user?: string;
+}
+/** where/which probe — goes through the shell so PATH seams (real or fake) apply. */
+export declare function forgeBinInstalled(host: ForgeHost): Promise<boolean>;
+export declare function forgeDetectHost(host: ForgeHost): Promise<ForgeHostStatus>;
+/** Detect both forges in parallel (forge_status / guidance basis). */
+export declare function forgeDetect(): Promise<ForgeHostStatus[]>;
+/** Run one forge CLI command (quoted, 60s timeout, agent cwd). Installed-check
+ *  first so a missing CLI yields the install hint, not cmd.exe mojibake.
+ *  (exec instead of execFile is deliberate: ag installs as ag.cmd, which
+ *  execFile cannot spawn on Windows since the 2024 security patch; quoteArg
+ *  hardens every shell metacharacter, so the injection surface is strictly
+ *  smaller than run_command's free-form line.) */
+export declare function forgeRun(host: ForgeHost, args: string[], opts?: {
+    timeoutMs?: number;
+    cwd?: string;
+}): Promise<{
+    ok: boolean;
+    output: string;
+}>;
+/** Tolerant JSON-array extraction: finds the first [ or { (both CLIs may
+ *  print a banner line before the payload), wraps single objects. */
+export declare function parseJsonOut(text: string): unknown[] | null;
+export declare function renderRepos(rows: unknown[]): string;
+export declare function renderPrs(rows: unknown[]): string;
+export declare function renderIssues(rows: unknown[]): string;
+export declare const forgeStatusTool: Tool;
+export declare const forgeRepoListTool: Tool;
+export declare const forgeRepoCreateTool: Tool;
+export declare const forgePrListTool: Tool;
+export declare const forgePrCreateTool: Tool;
+export declare const forgePrMergeTool: Tool;
+export declare const forgePrChecksTool: Tool;
+export declare const forgeIssueListTool: Tool;
+export declare const forgeIssueCreateTool: Tool;
+export declare const forgeReleaseCreateTool: Tool;
+export declare const forgeReleaseUploadTool: Tool;
+export declare const forgeRawTool: Tool;
+/** Start the web login flow and poll auth status until it succeeds or the
+ *  deadline passes. The device code / URL (gh prints them; ag opens the
+ *  browser) go to stderr immediately so terminal frontends show them during
+ *  the wait, and into the final result either way. */
+export declare function forgeLogin(host: ForgeHost, opts?: {
+    pollMs?: number;
+    timeoutMs?: number;
+    startFlow?: boolean;
+}): Promise<ToolResult>;
+export declare const forgeLoginTool: Tool;
+export declare const forgeTools: Tool[];

package/dist/forge.js

@@ -0,0 +1,635 @@
+/**
+ * @hmharness/agent - git forge tools (GitHub / AtomGit)
+ *
+ * First-class repository operations on the user's forges, driven by the
+ * platforms' own first-party CLIs: gh (GitHub) and ag (AtomGit — a
+ * gh-shaped command surface). Zero new dependencies: shell call + JSON
+ * parse. Credentials NEVER enter hmharness state — they stay in gh's
+ * keyring/hosts.yml and ag's own config storage; we only read `auth
+ * status` text to report the login user.
+ *
+ * Wire differences absorbed here (builders are pure + exported so tests
+ * assert exact argument assembly without a forge): gh `--json` takes a
+ * field list, ag `--json` is a boolean dump; gh selects repos with
+ * `-R owner/repo`, ag takes owner/repo positionally; gh release notes
+ * are `--title/--notes`, ag's are `--name/--body`; ag numbers arrive as
+ * strings. All commands run through exec() with manual quoting because
+ * ag installs as `ag.cmd` (npm global) — execFile cannot spawn .cmd on
+ * Windows (ENOENT/EINVAL since the 2024 security patch), and exec()
+ * resolves PATH exactly like the user's shell, fake-CLI test seams
+ * included.
+ */
+import { exec } from 'node:child_process';
+import { isAbsolute, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const execCb = promisify(exec);
+export const FORGE_BINS = { github: 'gh', atomgit: 'ag' };
+const PAGE_SIZE = 30;
+const MAX_PAGE = 10;
+const RUN_TIMEOUT_MS = 60_000;
+export function installHint(host) {
+    return host === 'github'
+        ? 'gh (GitHub CLI) is not installed. Install it first: `winget install GitHub.cli` on Windows, `brew install gh` on macOS — https://cli.github.com'
+        : 'ag (AtomGit CLI) is not installed. Install it first: `npm install -g @hust-open-atom-club/atomgit-cli` — https://atomgit.com/hust-open-atom-club/atomgit-cli';
+}
+export function loginHint(host) {
+    const bin = FORGE_BINS[host];
+    return `Not logged in to ${host}. Run the forge_login tool with host:"${host}" (it shows the device code/URL), or manually: \`${bin} auth login\``;
+}
+/** Shell-quote one argument. Windows: cmd.exe rules (wrap in "...", double
+ *  embedded quotes; a literal % inside quotes still expands — accepted as a
+ *  cmd.exe limitation, forge inputs rarely contain %). POSIX: single quotes
+ *  with the '\'' escape. (Pure, testable.) */
+export function quoteArg(s, platform = process.platform) {
+    if (s === '')
+        return '""';
+    if (platform === 'win32') {
+        if (!/[\s"&|<>^()%!]/.test(s))
+            return s;
+        return '"' + s.replace(/"/g, '""') + '"';
+    }
+    if (!/[\s'"$`\\&|;<>()*?\[\]#!]/.test(s))
+        return s;
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+/** Parse `auth status` text for BOTH CLIs' phrasings:
+ *  gh: "✓ Logged in to github.com account swsgbl (keyring)"
+ *  ag: "✓ Logged in to atomgit.com as demo-user" */
+export function parseAuthStatus(text) {
+    if (!/Logged in to/.test(text))
+        return { loggedIn: false };
+    const m = /Logged in to \S+ (?:account|as) (\S+?)[\s(\r]/.exec(text) ?? /Logged in to \S+ (?:account|as) (\S+)/.exec(text);
+    return { loggedIn: true, user: m?.[1] };
+}
+function str(v) { return v === undefined || v === null ? '' : String(v); }
+// ---------------- pure command builders ----------------
+export function repoListArgs(host, owner, page = 1) {
+    // neither CLI supports --page/--offset: page N fetches N*30 rows and the
+    // runner slices the window out (honest paging for N<=10 without --paginate)
+    const p = pageOf(page);
+    return [
+        'repo', 'list',
+        ...(owner ? [owner] : []),
+        '--limit', String(p * PAGE_SIZE),
+        ...(host === 'github' ? ['--json', 'name,visibility,updatedAt,pushedAt'] : ['--json']),
+    ];
+}
+function pageOf(page) {
+    const p = Math.floor(Number(page) || 1);
+    return Math.max(1, Math.min(p, MAX_PAGE));
+}
+export function repoCreateArgs(host, name, visibility, description) {
+    const desc = description ? [host === 'github' ? '--description' : '-d', description] : [];
+    return ['repo', 'create', name, visibility === 'private' ? '--private' : '--public', ...desc];
+}
+export function prListArgs(host, repo, state = 'open') {
+    const s = ['open', 'closed', 'all'].includes(state) ? state : 'open';
+    return host === 'github'
+        ? ['pr', 'list', '-R', repo, '--state', s, '--limit', '30', '--json', 'number,title,state,author,headRefName,url']
+        : ['pr', 'list', repo, '--state', s, '--limit', '30', '--json'];
+}
+export function prCreateArgs(host, repo, head, base, title, body) {
+    const b = body ? ['--body', body] : [];
+    const sel = host === 'github' ? ['-R', repo] : [repo];
+    return ['pr', 'create', ...sel, '--head', head, '--base', base, '--title', title, ...b];
+}
+export function prMergeArgs(host, repo, num, method = 'merge') {
+    if (host === 'github') {
+        const flag = method === 'squash' ? '--squash' : method === 'rebase' ? '--rebase' : '--merge';
+        return ['pr', 'merge', num, '-R', repo, flag];
+    }
+    // ag merges with the default method unless a flag says otherwise
+    const flag = method === 'squash' ? ['--squash'] : method === 'rebase' ? ['--rebase'] : [];
+    return ['pr', 'merge', repo, num, ...flag];
+}
+export function prChecksArgs(host, repo, num) {
+    return host === 'github'
+        ? ['pr', 'checks', num, '-R', repo, '--json', 'name,state']
+        : ['pr', 'checks', repo, num];
+}
+export function issueListArgs(host, repo, state = 'open') {
+    const s = ['open', 'closed', 'all'].includes(state) ? state : 'open';
+    return host === 'github'
+        ? ['issue', 'list', '-R', repo, '--state', s, '--limit', '30', '--json', 'number,title,state,author,url']
+        : ['issue', 'list', repo, '--state', s, '--limit', '30', '--json'];
+}
+export function issueCreateArgs(host, repo, title, body) {
+    const b = body ? ['--body', body] : [];
+    const sel = host === 'github' ? ['-R', repo] : [repo];
+    return ['issue', 'create', ...sel, '--title', title, ...b];
+}
+export function releaseCreateArgs(host, repo, tag, name, body, target) {
+    const t = target ? ['--target', target] : [];
+    return host === 'github'
+        ? ['release', 'create', tag, '-R', repo, '--title', name, '--notes', body, ...t]
+        : ['release', 'create', repo, tag, '--name', name, '--body', body, ...t]; // AtomGit API requires a non-empty body
+}
+export function releaseUploadArgs(host, repo, tag, file) {
+    return host === 'github'
+        ? ['release', 'upload', tag, file, '-R', repo]
+        : ['release', 'upload', repo, tag, file];
+}
+/** where/which probe — goes through the shell so PATH seams (real or fake) apply. */
+export async function forgeBinInstalled(host) {
+    const bin = FORGE_BINS[host];
+    const probe = process.platform === 'win32' ? `where ${bin}` : `command -v ${bin}`;
+    try {
+        await execCb(probe, { timeout: 10_000, windowsHide: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function forgeDetectHost(host) {
+    const bin = FORGE_BINS[host];
+    if (!(await forgeBinInstalled(host)))
+        return { host, bin, installed: false, loggedIn: false };
+    try {
+        const { stdout, stderr } = await execCb(`${bin} auth status`, { timeout: 15_000, windowsHide: true });
+        const p = parseAuthStatus(stdout + '\n' + stderr);
+        return { host, bin, installed: true, ...p };
+    }
+    catch (err) {
+        // both CLIs exit non-zero when logged out but still print their status
+        const e = err;
+        const p = parseAuthStatus([e.stdout, e.stderr].filter(Boolean).join('\n'));
+        return { host, bin, installed: true, ...p };
+    }
+}
+/** Detect both forges in parallel (forge_status / guidance basis). */
+export async function forgeDetect() {
+    return Promise.all(['github', 'atomgit'].map(forgeDetectHost));
+}
+/** Run one forge CLI command (quoted, 60s timeout, agent cwd). Installed-check
+ *  first so a missing CLI yields the install hint, not cmd.exe mojibake.
+ *  (exec instead of execFile is deliberate: ag installs as ag.cmd, which
+ *  execFile cannot spawn on Windows since the 2024 security patch; quoteArg
+ *  hardens every shell metacharacter, so the injection surface is strictly
+ *  smaller than run_command's free-form line.) */
+export async function forgeRun(host, args, opts = {}) {
+    const bin = FORGE_BINS[host];
+    if (!(await forgeBinInstalled(host)))
+        return { ok: false, output: installHint(host) };
+    const line = [bin, ...args.map((a) => quoteArg(String(a)))].join(' ');
+    try {
+        const { stdout, stderr } = await execCb(line, {
+            cwd: opts.cwd, timeout: opts.timeoutMs ?? RUN_TIMEOUT_MS, windowsHide: true, maxBuffer: 8 * 1024 * 1024,
+        });
+        const out = (stdout || '').trim() + (stderr && stderr.trim() ? `\n[stderr]\n${stderr.trim()}` : '');
+        return { ok: true, output: out.trim() || '(no output)' };
+    }
+    catch (err) {
+        const e = err;
+        if (e.killed)
+            return { ok: false, output: `${bin} command timed out after ${opts.timeoutMs ?? RUN_TIMEOUT_MS}ms — narrow it (add --limit, a smaller page) and retry.` };
+        const out = [e.stdout, e.stderr, e.message].filter(Boolean).map((s) => String(s).trim()).filter(Boolean).join('\n');
+        return { ok: false, output: out.slice(0, 20_000) || `${bin} failed (no output)` };
+    }
+}
+/** Guard shared by every forge tool except status/login/raw: valid host,
+ *  CLI installed, logged in — or the honest, actionable error. */
+async function guard(host) {
+    const st = await forgeDetectHost(host);
+    if (!st.installed)
+        return { output: installHint(host), isError: true };
+    if (!st.loggedIn)
+        return { output: loginHint(host), isError: true };
+    return null;
+}
+function hostOf(args) {
+    const h = String(args.host ?? '');
+    if (h === 'github' || h === 'atomgit')
+        return { host: h };
+    return { err: { output: `host must be 'github' or 'atomgit' (got '${h}')`, isError: true } };
+}
+// ---------------- renderers (forge JSON -> compact lines) ----------------
+/** Tolerant JSON-array extraction: finds the first [ or { (both CLIs may
+ *  print a banner line before the payload), wraps single objects. */
+export function parseJsonOut(text) {
+    const idxs = ['[', '{'].map((c) => text.indexOf(c)).filter((i) => i >= 0);
+    if (!idxs.length)
+        return null;
+    try {
+        const v = JSON.parse(text.slice(Math.min(...idxs)));
+        return Array.isArray(v) ? v : [v];
+    }
+    catch {
+        return null;
+    }
+}
+export function renderRepos(rows) {
+    const lines = rows.map((r) => {
+        const o = r;
+        const name = str(o.name) || str(o.fullName) || '?';
+        const vis = (str(o.visibility) || (o.isPrivate ? 'private' : '')).toLowerCase();
+        // AtomGit's repo payload has no pushedAt — say so instead of inventing one
+        const pushed = o.pushedAt ? str(o.pushedAt) : 'n/a (host does not report)';
+        return `${name} [${vis.includes('priv') ? 'private' : 'public'}] updated=${str(o.updatedAt) || '?'} pushed=${pushed}`;
+    });
+    return lines.length ? lines.join('\n') : '(no repositories found)';
+}
+export function renderPrs(rows) {
+    const lines = rows.map((r) => {
+        const o = r;
+        const author = typeof o.author === 'object' && o.author ? str(o.author.login) : str(o.author);
+        const head = str(o.headRefName) || str(o.head);
+        return `#${str(o.number)} [${str(o.state) || '?'}] ${str(o.title)} — ${author || '?'}${head ? ` (${head})` : ''} ${str(o.url)}`.trimEnd();
+    });
+    return lines.length ? lines.join('\n') : '(no pull requests found)';
+}
+export function renderIssues(rows) {
+    const lines = rows.map((r) => {
+        const o = r;
+        const author = typeof o.author === 'object' && o.author ? str(o.author.login) : str(o.author);
+        return `#${str(o.number)} [${str(o.state) || '?'}] ${str(o.title)} — ${author || '?'} ${str(o.url)}`.trimEnd();
+    });
+    return lines.length ? lines.join('\n') : '(no issues found)';
+}
+// ---------------- tools ----------------
+export const forgeStatusTool = {
+    name: 'forge_status',
+    description: 'Show GitHub (gh) and AtomGit (ag) CLI install + login status at a glance. Call this FIRST for any repository task on a forge.',
+    parameters: { type: 'object', properties: {}, required: [] },
+    async execute() {
+        const rows = await forgeDetect();
+        const lines = rows.map((s) => {
+            if (!s.installed)
+                return `${s.host}: NOT installed — ${installHint(s.host)}`;
+            if (!s.loggedIn)
+                return `${s.host}: installed (${s.bin}), NOT logged in — ${loginHint(s.host)}`;
+            return `${s.host}: installed (${s.bin}), logged in as ${s.user ?? '(user unknown)'}`;
+        });
+        return { output: lines.join('\n') };
+    },
+};
+export const forgeRepoListTool = {
+    name: 'forge_repo_list',
+    description: 'List repositories on a forge — your own, or an owner/org\'s. host: github|atomgit; optional owner, page (30/page, max 10).',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            owner: { type: 'string', description: 'owner/org login (default: the logged-in account)' },
+            page: { type: 'number', description: '1-based page of 30 (max 10)' },
+        },
+        required: ['host'],
+    },
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        const page = pageOf(Number(args.page ?? 1));
+        const r = await forgeRun(host, repoListArgs(host, args.owner ? String(args.owner) : undefined, page), { cwd: ctx.cwd });
+        if (!r.ok)
+            return { output: r.output, isError: true };
+        const rows = parseJsonOut(r.output);
+        if (!rows)
+            return { output: `could not parse ${host} repo list JSON — raw output:\n${r.output.slice(0, 4_000)}`, isError: true };
+        const win = rows.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);
+        return { output: `${host} repositories (page ${page}${args.owner ? `, owner ${args.owner}` : ''}):\n${renderRepos(win)}` };
+    },
+};
+export const forgeRepoCreateTool = {
+    name: 'forge_repo_create',
+    description: 'Create a repository on a forge. host: github|atomgit; name (may be owner/name to create under an org); visibility public|private (default private); optional description.',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            name: { type: 'string', description: 'repository name (or owner/name)' },
+            visibility: { type: 'string', description: "'public' or 'private' (default private)" },
+            description: { type: 'string', description: 'one-line description' },
+        },
+        required: ['host', 'name'],
+    },
+    needsApproval: () => true,
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        const vis = String(args.visibility ?? 'private') === 'public' ? 'public' : 'private';
+        const r = await forgeRun(host, repoCreateArgs(host, String(args.name ?? ''), vis, args.description ? String(args.description) : undefined), { cwd: ctx.cwd });
+        return { output: `created ${vis} repo ${args.name} on ${host}:\n${r.output}`, isError: !r.ok };
+    },
+};
+export const forgePrListTool = {
+    name: 'forge_pr_list',
+    description: 'List pull requests of owner/repo on a forge. host: github|atomgit; repo owner/repo; state open|closed|all (default open).',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            repo: { type: 'string', description: 'owner/repo' },
+            state: { type: 'string', description: 'open | closed | all (default open)' },
+        },
+        required: ['host', 'repo'],
+    },
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        const r = await forgeRun(host, prListArgs(host, String(args.repo ?? ''), String(args.state ?? 'open')), { cwd: ctx.cwd });
+        if (!r.ok)
+            return { output: r.output, isError: true };
+        const rows = parseJsonOut(r.output);
+        if (!rows)
+            return { output: `could not parse ${host} pr list JSON — raw output:\n${r.output.slice(0, 4_000)}`, isError: true };
+        return { output: `${host} pull requests (${args.repo}, ${String(args.state ?? 'open')}):\n${renderPrs(rows)}` };
+    },
+};
+export const forgePrCreateTool = {
+    name: 'forge_pr_create',
+    description: 'Create a pull request. host: github|atomgit; repo owner/repo; head branch; base branch; title; optional body. Branch must already be pushed.',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            repo: { type: 'string', description: 'owner/repo' },
+            head: { type: 'string', description: 'source branch (e.g. feat/x)' },
+            base: { type: 'string', description: 'target branch (e.g. main)' },
+            title: { type: 'string', description: 'PR title' },
+            body: { type: 'string', description: 'PR description (markdown)' },
+        },
+        required: ['host', 'repo', 'head', 'base', 'title'],
+    },
+    needsApproval: () => true,
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        const r = await forgeRun(host, prCreateArgs(host, String(args.repo ?? ''), String(args.head ?? ''), String(args.base ?? ''), String(args.title ?? ''), args.body ? String(args.body) : undefined), { cwd: ctx.cwd });
+        return { output: `pull request created on ${host}:\n${r.output}`, isError: !r.ok };
+    },
+};
+export const forgePrMergeTool = {
+    name: 'forge_pr_merge',
+    description: 'Merge a pull request. host: github|atomgit; repo owner/repo; num PR number; method merge|squash|rebase (default merge). Irreversible — confirm with the user first.',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            repo: { type: 'string', description: 'owner/repo' },
+            num: { type: 'string', description: 'PR number' },
+            method: { type: 'string', description: 'merge | squash | rebase (default merge)' },
+        },
+        required: ['host', 'repo', 'num'],
+    },
+    needsApproval: () => true,
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        const m = String(args.method ?? 'merge');
+        const r = await forgeRun(host, prMergeArgs(host, String(args.repo ?? ''), String(args.num ?? ''), m === 'squash' ? 'squash' : m === 'rebase' ? 'rebase' : 'merge'), { cwd: ctx.cwd });
+        return { output: r.output, isError: !r.ok };
+    },
+};
+export const forgePrChecksTool = {
+    name: 'forge_pr_checks',
+    description: 'Show CI checks/status for a pull request. host: github|atomgit; repo owner/repo; num PR number. Older ag builds without `pr checks` report it honestly.',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            repo: { type: 'string', description: 'owner/repo' },
+            num: { type: 'string', description: 'PR number' },
+        },
+        required: ['host', 'repo', 'num'],
+    },
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        const r = await forgeRun(host, prChecksArgs(host, String(args.repo ?? ''), String(args.num ?? '')), { cwd: ctx.cwd });
+        if (r.ok) {
+            const rows = parseJsonOut(r.output); // gh --json name,state
+            const body = rows && rows.length && typeof rows[0]?.name === 'string'
+                ? rows.map((x) => { const o = x; return `${str(o.name)}: ${str(o.state)}`; }).join('\n')
+                : r.output; // ag prints a human table — pass it through as-is
+            return { output: `checks for ${host} PR #${args.num}:\n${body}` };
+        }
+        return {
+            output: `${r.output}\n(If your ag version predates \`ag pr checks\` — added in atomgit-cli 0.7.x — the host genuinely does not expose checks here; tell the user that instead of guessing.)`,
+            isError: true,
+        };
+    },
+};
+export const forgeIssueListTool = {
+    name: 'forge_issue_list',
+    description: 'List issues of owner/repo on a forge. host: github|atomgit; repo owner/repo; state open|closed|all (default open).',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            repo: { type: 'string', description: 'owner/repo' },
+            state: { type: 'string', description: 'open | closed | all (default open)' },
+        },
+        required: ['host', 'repo'],
+    },
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        const r = await forgeRun(host, issueListArgs(host, String(args.repo ?? ''), String(args.state ?? 'open')), { cwd: ctx.cwd });
+        if (!r.ok)
+            return { output: r.output, isError: true };
+        const rows = parseJsonOut(r.output);
+        if (!rows)
+            return { output: `could not parse ${host} issue list JSON — raw output:\n${r.output.slice(0, 4_000)}`, isError: true };
+        return { output: `${host} issues (${args.repo}, ${String(args.state ?? 'open')}):\n${renderIssues(rows)}` };
+    },
+};
+export const forgeIssueCreateTool = {
+    name: 'forge_issue_create',
+    description: 'Create an issue. host: github|atomgit; repo owner/repo; title; optional body.',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            repo: { type: 'string', description: 'owner/repo' },
+            title: { type: 'string', description: 'issue title' },
+            body: { type: 'string', description: 'issue body (markdown)' },
+        },
+        required: ['host', 'repo', 'title'],
+    },
+    needsApproval: () => true,
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        const r = await forgeRun(host, issueCreateArgs(host, String(args.repo ?? ''), String(args.title ?? ''), args.body ? String(args.body) : undefined), { cwd: ctx.cwd });
+        return { output: `issue created on ${host}:\n${r.output}`, isError: !r.ok };
+    },
+};
+export const forgeReleaseCreateTool = {
+    name: 'forge_release_create',
+    description: 'Create a release from a tag. host: github|atomgit; repo owner/repo; tag; name (release title); body (release notes — required, AtomGit rejects empty); optional target branch/SHA when the tag does not exist yet.',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            repo: { type: 'string', description: 'owner/repo' },
+            tag: { type: 'string', description: 'tag name, e.g. v1.2.0' },
+            name: { type: 'string', description: 'release title' },
+            body: { type: 'string', description: 'release notes (required)' },
+            target: { type: 'string', description: 'target branch or commit SHA (creates the tag if absent)' },
+        },
+        required: ['host', 'repo', 'tag', 'name', 'body'],
+    },
+    needsApproval: () => true,
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        if (!String(args.body ?? '').trim())
+            return { output: 'body (release notes) is required — AtomGit rejects an empty body and gh would open an interactive editor.', isError: true };
+        const r = await forgeRun(host, releaseCreateArgs(host, String(args.repo ?? ''), String(args.tag ?? ''), String(args.name ?? ''), String(args.body), args.target ? String(args.target) : undefined), { cwd: ctx.cwd });
+        return { output: `release ${args.tag} created on ${host}:\n${r.output}`, isError: !r.ok };
+    },
+};
+export const forgeReleaseUploadTool = {
+    name: 'forge_release_upload',
+    description: 'Upload a file as an asset of an existing release. host: github|atomgit; repo owner/repo; tag; file path (must exist; its full path, target repo and tag are shown on the approval card — uploading moves data OFF this machine).',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            repo: { type: 'string', description: 'owner/repo' },
+            tag: { type: 'string', description: 'release tag' },
+            file: { type: 'string', description: 'local file path to upload' },
+        },
+        required: ['host', 'repo', 'tag', 'file'],
+    },
+    needsApproval: () => true,
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        const g = await guard(host);
+        if (g)
+            return g;
+        const file = isAbsolute(String(args.file ?? '')) ? String(args.file ?? '') : resolve(ctx.cwd, String(args.file ?? ''));
+        try {
+            await import('node:fs/promises').then((f) => f.access(file));
+        }
+        catch {
+            return { output: `file not found: ${file}`, isError: true };
+        }
+        const r = await forgeRun(host, releaseUploadArgs(host, String(args.repo ?? ''), String(args.tag ?? ''), file), { cwd: ctx.cwd });
+        return { output: r.output, isError: !r.ok };
+    },
+};
+export const forgeRawTool = {
+    name: 'forge_raw',
+    description: 'DANGEROUS: pass raw arguments straight to gh/ag (host selects the binary). Only for operations the dedicated forge_* tools cannot express. Approval-gated; YOLO/auto modes pass it through.',
+    parameters: {
+        type: 'object',
+        properties: {
+            host: { type: 'string', description: "'github' or 'atomgit'" },
+            args: { type: 'array', items: { type: 'string' }, description: 'raw CLI arguments, e.g. ["api","user"]' },
+        },
+        required: ['host', 'args'],
+    },
+    needsApproval: () => true,
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        if (!Array.isArray(args.args) || !args.args.length)
+            return { output: 'args must be a non-empty array of strings', isError: true };
+        const r = await forgeRun(host, args.args.map(String), { cwd: ctx.cwd });
+        return { output: `[${FORGE_BINS[host]} ${args.args.map(String).join(' ')}]\n${r.output}`, isError: !r.ok };
+    },
+};
+// ---------------- login guidance ----------------
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Start the web login flow and poll auth status until it succeeds or the
+ *  deadline passes. The device code / URL (gh prints them; ag opens the
+ *  browser) go to stderr immediately so terminal frontends show them during
+ *  the wait, and into the final result either way. */
+export async function forgeLogin(host, opts = {}) {
+    const bin = FORGE_BINS[host];
+    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const pollMs = opts.pollMs ?? 4_000;
+    const already = await forgeDetectHost(host);
+    if (!already.installed)
+        return { output: installHint(host), isError: true };
+    if (already.loggedIn)
+        return { output: `already logged in to ${host} as ${already.user ?? '(user unknown)'} — nothing to do.` };
+    let early = '';
+    if (opts.startFlow !== false) {
+        const flow = host === 'github' ? `${bin} auth login --web -h github.com --skip-ssh-key` : `${bin} auth login`;
+        const child = exec(flow, { timeout: timeoutMs + 30_000, windowsHide: true }, () => undefined);
+        let buf = '';
+        const grab = (d) => { buf += String(d); };
+        child.stdout?.on('data', grab);
+        child.stderr?.on('data', grab);
+        await sleep(Math.min(6_000, Math.max(pollMs * 2, 500))); // give the CLI a moment to print the code/URL
+        const code = /\b([A-Z0-9]{4,8}-[A-Z0-9]{4,8})\b/.exec(buf)?.[1];
+        const url = /https:\/\/\S+/.exec(buf)?.[0];
+        early = [code ? `device code: ${code}` : '', url ? `authorization URL: ${url}` : ''].filter(Boolean).join('\n');
+        if (early)
+            console.error(`[forge_login:${host}] ${early} — complete it in the browser; waiting for the login to land...`);
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await sleep(pollMs);
+        const st = await forgeDetectHost(host);
+        if (st.loggedIn)
+            return { output: `login complete: ${host} as ${st.user ?? '(user unknown)'}.${early ? `\n(${early})` : ''}` };
+    }
+    return {
+        output: `login did not complete within ${Math.round(timeoutMs / 1000)}s.${early ? `\n${early}\nFinish it in the browser, then confirm with forge_status.` : `\nNo device code/URL was captured — start it manually: \`${bin} auth login\`, then confirm with forge_status.`}`,
+        isError: true,
+    };
+}
+export const forgeLoginTool = {
+    name: 'forge_login',
+    description: 'Guide the user through logging in to a forge (host: github|atomgit): starts `gh auth login --web` / `ag auth login` (the user completes it in the browser), shows the device code/URL, and polls until logged in (3 min timeout).',
+    parameters: {
+        type: 'object',
+        properties: { host: { type: 'string', description: "'github' or 'atomgit'" } },
+        required: ['host'],
+    },
+    async execute(args, ctx) {
+        const { host, err } = hostOf(args);
+        if (!host || err)
+            return err;
+        return forgeLogin(host);
+    },
+};
+export const forgeTools = [
+    forgeStatusTool, forgeRepoListTool, forgeRepoCreateTool,
+    forgePrListTool, forgePrCreateTool, forgePrMergeTool, forgePrChecksTool,
+    forgeIssueListTool, forgeIssueCreateTool,
+    forgeReleaseCreateTool, forgeReleaseUploadTool,
+    forgeRawTool, forgeLoginTool,
+];

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { baseTools, readFileTool, writeFileTool, listDirTool, runCommandTool, rememberTool, seeImageTool } from './tools.js';
+export { forgeTools, forgeDetect, forgeDetectHost, forgeRun, forgeLogin, quoteArg, parseAuthStatus, parseJsonOut, renderRepos, renderPrs, renderIssues, repoListArgs, repoCreateArgs, prListArgs, prCreateArgs, prMergeArgs, prChecksArgs, issueListArgs, issueCreateArgs, releaseCreateArgs, releaseUploadArgs, FORGE_BINS, installHint, loginHint, type ForgeHost, type ForgeHostStatus, } from './forge.js';
 export { manifestFor, capabilityReport, authorize, type CapabilityManifest, type CapabilityRisk, type PolicyMode } from './capability.js';
 export { checkpointProject, createProject, findProject, interruptProject, listProjects, loadProject, projectFor, releaseProject, restoreCheckpoint, resumeBundle, transitionProject, attachRun, newProjectId, type CheckpointRef, type DecisionEntry, type ProjectRecord, type ProjectState, } from './project.js';
 export { mechanicalGate, parseVerdict, runPipeline, type PipelineOptions, type PipelineReport, type StageRecord, type StageRole, } from './pipeline.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { baseTools, readFileTool, writeFileTool, listDirTool, runCommandTool, rememberTool, seeImageTool } from "./tools.js";
+export { forgeTools, forgeDetect, forgeDetectHost, forgeRun, forgeLogin, quoteArg, parseAuthStatus, parseJsonOut, renderRepos, renderPrs, renderIssues, repoListArgs, repoCreateArgs, prListArgs, prCreateArgs, prMergeArgs, prChecksArgs, issueListArgs, issueCreateArgs, releaseCreateArgs, releaseUploadArgs, FORGE_BINS, installHint, loginHint, } from "./forge.js";
 export { manifestFor, capabilityReport, authorize } from "./capability.js";
 export { checkpointProject, createProject, findProject, interruptProject, listProjects, loadProject, projectFor, releaseProject, restoreCheckpoint, resumeBundle, transitionProject, attachRun, newProjectId, } from "./project.js";
 export { mechanicalGate, parseVerdict, runPipeline, } from "./pipeline.js";

package/dist/prompt.js

@@ -28,6 +28,8 @@ export function buildSystemPrompt(opts) {
     '', '## Where tools and skills live on this machine (check these FIRST when asked "is X installed")', `Other agent frameworks share this machine; their skills/plugins/tools are at known paths under the home directory. When asked to check whether a tool/skill/package is installed, or to find/configure an existing one, probe these locations (in order) before concluding "not installed":`, `- ~/.zcode/skills/<name>/  (ZCode skills with SKILL.md, scripts/, .env)`, `- ~/.claude/skills/<name>/  (Claude Code skills with SKILL.md, scripts/)`, `- ~/.codex/skills/<name>/   (Codex skills with SKILL.md, scripts/)`, `- ~/.dsh/skills/<name>/ and ~/.dsh-hm/skills/<name>/  (deepseek-harness skills)`, `- ~/.jcode/skills/<name>/   (JCode skills)`, `- ~/.agent-reach-venv/ and ~/.agent-reach/tools/ (Agent Reach CLI + platform tools)`, `- ~/.local/bin/  (user-installed executables; PATH may not include it - check dir /b not just where)`, `Home directory: ${homedir()}`, 'When found, read the tool\'s SKILL.md or README.md for its usage; copy or reference its scripts rather than reinventing. If the user asks to "configure it for hmharness", check whether it exposes an MCP endpoint (add to config.json mcpServers), an HTTP API (add a provider), or a CLI (register as a skill via `hmh skills add <path>`).', 
     // ---- 鸿蒙域 ----
     '', 'HarmonyOS development is your home domain: DevEco Studio toolchain, hvigor builds, ohpm packages, hdc devices, ArkTS/ArkUI, OpenHarmony and Cangjie. When a task touches it, prefer the harmony_* tools and precise toolchain knowledge.', 
+    // ---- Git forge 域(GitHub / AtomGit,2026-10-30 用户特性) ----
+    '', '## Git forges (GitHub / AtomGit)', 'Repository operations on GitHub or AtomGit — listing/creating repos, PRs, issues, releases, checking CI — go through the forge_* tools (host: "github" → gh CLI, "atomgit" → ag CLI). Do NOT send the user to the website for anything a forge_* tool can do.', 'Call forge_status first; when a host is not logged in, run forge_login for it (it shows the device code / URL the user must complete in the browser) — do not tell the user to run gh/ag commands by hand.', 'Credentials live in gh/ag\'s own storage and never pass through you: never ask for or store a platform token yourself.', 
     // ---- 通用工作风格 ----
     '', 'Working style: read before writing; prefer small focused commands; verify results; state tradeoffs briefly. For risky operations (deleting, overwriting, publishing) say what will happen first. When a command fails twice with the same error, switch strategy instead of repeating it. For multi-line/quoted logic, write a temp .cjs file and run it with node - never fight cmd.exe quoting with node -e one-liners.', '', 'Anti re-verification: when you have already established a fact in this conversation (it is in your earlier text, in the rolling digest, or in a pruned-but-head-visible tool result), state it and move on — do NOT re-run the same search or command to "confirm" it again. Only re-check when you have concrete evidence the situation changed (a file was modified, a command failed differently). Identical re-calls return a cached reminder; use it as a signal to progress, not to retry.', 
     // ---- [Codex] 最终答复结构(gpt_5_2_prompt "Final answer structure and style guidelines" 的 hmh 压缩版) ----

package/dist/runner.js

@@ -22,6 +22,7 @@ import { pageReadSink, lspObserveSink, observeBuildTools } from "./code-wm-recor
 import * as readline from 'node:readline/promises';
 import { stdin } from 'node:process';
 import { baseTools } from "./tools.js";
+import { forgeTools } from "./forge.js";
 import { buildSystemPrompt } from "./prompt.js";
 import { strings } from "./i18n.js";
 import { makeSpawnTool, MAX_SPAWN_DEPTH } from "./spawn.js";
@@ -40,7 +41,7 @@ export function toServerConfig(c) {
 export const spawnBase = {};
 export function nativeRegistry(depth, opts = {}) {
     const reg = new Registry();
-    reg.registerAll(baseTools).registerAll(observeBuildTools(harmonyTools, homeDir())).registerAll(opsTools);
+    reg.registerAll(baseTools).registerAll(observeBuildTools(harmonyTools, homeDir())).registerAll(opsTools).registerAll(forgeTools);
     // W6: LSP Tier-0 code-intelligence tools — registered ONLY when a real
     // server is discoverable on PATH; a machine with no language servers
     // must not carry dead tools. Discovery is synchronous (memoized PATH

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/agent",
-  "version": "0.23.46",
+  "version": "0.23.48",
   "description": "hmharness agent execution layer: base tools, system prompt, sub-agent spawn, and the shared task runner that frontends (cli, web) drive.",
   "type": "module",
   "main": "dist/index.js",
@@ -15,16 +15,16 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@hmharness/cognitive": "0.23.46",
-    "@hmharness/domain-harmony": "0.23.46",
-    "@hmharness/domain-ops": "0.23.46",
-    "@hmharness/evolution": "0.23.46",
-    "@hmharness/kernel": "0.23.46",
-    "@hmharness/observability": "0.23.46",
-    "@hmharness/sandbox": "0.23.46",
-    "@hmharness/lsp": "0.23.46",
-    "@hmharness/browser": "0.23.46",
-    "@hmharness/extension": "0.23.46"
+    "@hmharness/cognitive": "0.23.48",
+    "@hmharness/domain-harmony": "0.23.48",
+    "@hmharness/domain-ops": "0.23.48",
+    "@hmharness/evolution": "0.23.48",
+    "@hmharness/kernel": "0.23.48",
+    "@hmharness/observability": "0.23.48",
+    "@hmharness/sandbox": "0.23.48",
+    "@hmharness/lsp": "0.23.48",
+    "@hmharness/browser": "0.23.48",
+    "@hmharness/extension": "0.23.48"
   },
   "files": [
     "dist"