@aiwg/cli 2026.7.24 → 2026.8.0

package/dist/src/jobs/runner.js

@@ -0,0 +1,315 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { approvalLabel, approvalRequired, resolveWorkspaceFile } from './flow.js';
+const CLAIM_PREFIX = '<!-- aiwg-job:claim ';
+const COMPLETE_PREFIX = '<!-- aiwg-job:complete ';
+const FAILURE_PREFIX = '<!-- aiwg-job:failed ';
+function marker(body, prefix) {
+    const line = body.split(/\r?\n/u).find(candidate => candidate.startsWith(prefix) && candidate.endsWith(' -->'));
+    if (!line)
+        return null;
+    try {
+        return JSON.parse(line.slice(prefix.length, -4));
+    }
+    catch {
+        return null;
+    }
+}
+function jobKey(flow, issue) {
+    return createHash('sha256')
+        .update(`${flow.metadata.name}\0${flow.metadata.revision}\0${issue}`)
+        .digest('hex');
+}
+function claimBody(flow, issue, runnerId, expiresAt) {
+    const value = {
+        job: flow.metadata.name,
+        revision: flow.metadata.revision,
+        idempotencyKey: jobKey(flow, issue.number),
+        runnerId,
+        expiresAt,
+    };
+    return `${CLAIM_PREFIX}${JSON.stringify(value)} -->\n\nAIWG external job claim. Execution remains subject to the reviewed flow contract.`;
+}
+function completionBody(flow, result) {
+    const value = {
+        job: flow.metadata.name,
+        revision: flow.metadata.revision,
+        idempotencyKey: result.idempotencyKey,
+        externalResultUrl: result.externalResultUrl,
+    };
+    return [
+        `${COMPLETE_PREFIX}${JSON.stringify(value)} -->`,
+        '',
+        `AIWG external job **${flow.metadata.name}** completed.`,
+        `- Idempotency key: \`${result.idempotencyKey}\``,
+        `- External result: ${result.externalResultUrl}`,
+        `- Account: \`${result.account}\``,
+        `- Verification: \`${result.verification.replace(/[\r\n`]+/gu, ' ').slice(0, 1000)}\``,
+    ].join('\n');
+}
+function failureBody(flow, key, message) {
+    const safeMessage = message.replace(/[\r\n]+/gu, ' ').slice(0, 1000);
+    const value = {
+        job: flow.metadata.name,
+        revision: flow.metadata.revision,
+        idempotencyKey: key,
+        reason: safeMessage,
+    };
+    return [
+        `${FAILURE_PREFIX}${JSON.stringify(value)} -->`,
+        '',
+        `AIWG external job **${flow.metadata.name}** did not pass completion verification.`,
+        `- Idempotency key: \`${key}\``,
+        `- Result: no completion marker was written`,
+        `- Reason: ${safeMessage}`,
+    ].join('\n');
+}
+function failedBy(comments, actor, key) {
+    for (const comment of comments) {
+        if (comment.author !== actor)
+            continue;
+        const parsed = marker(comment.body, FAILURE_PREFIX);
+        if (parsed?.idempotencyKey === key)
+            return parsed;
+    }
+    return null;
+}
+function validateExternalUrl(flow, value) {
+    const resultUrl = new URL(value);
+    if (!flow.spec.security.allowedOrigins.includes(resultUrl.origin))
+        throw new Error('external result origin is not allow-listed');
+    if (resultUrl.username || resultUrl.password)
+        throw new Error('external result URL must not contain user information');
+    for (const parameter of resultUrl.searchParams.keys()) {
+        if (/(auth|cookie|credential|key|password|secret|session|signature|token)/iu.test(parameter)) {
+            throw new Error('external result URL contains a sensitive query parameter');
+        }
+    }
+    return resultUrl;
+}
+function completedBy(flow, comments, actor, key) {
+    for (const comment of comments) {
+        if (comment.author !== actor)
+            continue;
+        const parsed = marker(comment.body, COMPLETE_PREFIX);
+        if (parsed?.idempotencyKey === key && typeof parsed.externalResultUrl === 'string') {
+            validateExternalUrl(flow, parsed.externalResultUrl);
+            return parsed;
+        }
+    }
+    return null;
+}
+function activeClaims(comments, actor, key, now) {
+    return comments.flatMap(comment => {
+        if (comment.author !== actor)
+            return [];
+        const parsed = marker(comment.body, CLAIM_PREFIX);
+        const expiry = parsed ? Date.parse(parsed.expiresAt) : Number.NaN;
+        if (!parsed || parsed.idempotencyKey !== key || !Number.isFinite(expiry) || expiry <= now)
+            return [];
+        return [{ comment, marker: parsed }];
+    }).sort((left, right) => left.comment.id - right.comment.id);
+}
+async function isInside(file, roots) {
+    let resolved;
+    try {
+        resolved = await fs.realpath(file);
+    }
+    catch {
+        return false;
+    }
+    const canonicalRoots = await Promise.all(roots.map(root => fs.realpath(root)));
+    return canonicalRoots.some(root => {
+        const relation = path.relative(root, resolved);
+        return relation === '' || (!relation.startsWith('..') && !path.isAbsolute(relation));
+    });
+}
+async function validateResult(flow, key, finalMessage) {
+    let value;
+    try {
+        value = JSON.parse(finalMessage);
+    }
+    catch {
+        throw new Error('executor final response is not JSON');
+    }
+    if (value.idempotencyKey !== key)
+        throw new Error('executor returned a different idempotency key');
+    if (typeof value.externalResultUrl !== 'string')
+        throw new Error('externalResultUrl is required');
+    validateExternalUrl(flow, value.externalResultUrl);
+    if (typeof value.account !== 'string' || !flow.spec.security.allowedAccounts.includes(value.account)) {
+        throw new Error('result account is not allow-listed');
+    }
+    if (typeof value.verification !== 'string' || !value.verification.trim())
+        throw new Error('verification evidence is required');
+    const attachments = value.attachmentPaths ?? [];
+    if (!Array.isArray(attachments) || !attachments.every(item => typeof item === 'string')) {
+        throw new Error('attachmentPaths must be an array of paths');
+    }
+    const approvedAttachments = await Promise.all(attachments.map(item => isInside(item, flow.spec.security.approvedAttachmentRoots)));
+    if (!approvedAttachments.every(Boolean)) {
+        throw new Error('result references an attachment outside approved roots');
+    }
+    return {
+        status: 'completed', idempotencyKey: key, externalResultUrl: value.externalResultUrl,
+        account: value.account, verification: value.verification, attachmentPaths: attachments,
+    };
+}
+async function delay(ms, signal) {
+    if (ms <= 0)
+        return;
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }, { once: true });
+    });
+}
+async function acquireLock(stateRoot, flow) {
+    const directory = path.join(stateRoot, 'locks');
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const file = path.join(directory, `${flow.metadata.name}.lock`);
+    const create = async () => {
+        const handle = await fs.open(file, 'wx', 0o600);
+        await handle.writeFile(JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
+        await handle.close();
+    };
+    try {
+        await create();
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        let stale = false;
+        try {
+            const lock = JSON.parse(await fs.readFile(file, 'utf8'));
+            const tooOld = !lock.startedAt || Date.now() - Date.parse(lock.startedAt) > (flow.spec.workItem.claimTtlSeconds ?? 900) * 1000;
+            let alive = false;
+            if (typeof lock.pid === 'number') {
+                try {
+                    process.kill(lock.pid, 0);
+                    alive = true;
+                }
+                catch { /* process is gone or inaccessible */ }
+            }
+            stale = tooOld && !alive;
+        }
+        catch {
+            stale = true;
+        }
+        if (!stale)
+            throw new Error(`job ${flow.metadata.name} is already running on this host`);
+        await fs.unlink(file).catch(() => undefined);
+        await create();
+    }
+    return async () => { await fs.unlink(file).catch(() => undefined); };
+}
+async function readRecovery(stateRoot, key) {
+    try {
+        return JSON.parse(await fs.readFile(path.join(stateRoot, 'results', `${key}.json`), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+async function writeRecovery(stateRoot, result) {
+    const directory = path.join(stateRoot, 'results');
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const target = path.join(directory, `${result.idempotencyKey}.json`);
+    const temporary = `${target}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
+    await fs.rename(temporary, target);
+}
+async function writeRunRecord(runDirectory, record) {
+    const target = path.join(runDirectory, 'run.json');
+    const temporary = `${target}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    await fs.rename(temporary, target);
+}
+export async function runExternalJob(options) {
+    const { flow, client, executor, signal } = options;
+    const now = options.now ?? Date.now;
+    const stateRoot = options.stateRoot ?? path.join(flow.spec.executor.workspace, '.aiwg', 'jobs');
+    if (path.resolve(stateRoot) === path.parse(path.resolve(stateRoot)).root)
+        throw new Error('job state root must not be a filesystem root');
+    const release = await acquireLock(stateRoot, flow);
+    try {
+        const actor = await client.currentUser(signal);
+        const requiredLabels = [...flow.spec.workItem.eligibleLabels];
+        if (approvalRequired(flow) && !requiredLabels.includes(approvalLabel(flow)))
+            requiredLabels.push(approvalLabel(flow));
+        const issues = await client.listOpenIssues(requiredLabels, signal);
+        let lostClaim = false;
+        for (const issue of issues) {
+            const key = jobKey(flow, issue.number);
+            let comments = await client.listComments(issue.number, signal);
+            const completed = completedBy(flow, comments, actor, key);
+            if (completed)
+                return { status: 'already-completed', issue: issue.number, idempotencyKey: key, externalResultUrl: completed.externalResultUrl };
+            const priorFailure = failedBy(comments, actor, key);
+            if (priorFailure)
+                return { status: 'failed-verification', issue: issue.number, idempotencyKey: key, message: priorFailure.reason };
+            const recovered = await readRecovery(stateRoot, key);
+            if (recovered?.status === 'completed') {
+                const verifiedRecovery = { ...await validateResult(flow, key, JSON.stringify(recovered)), issue: issue.number };
+                await client.addComment(issue.number, completionBody(flow, verifiedRecovery), signal);
+                return { ...verifiedRecovery, status: 'already-completed' };
+            }
+            if (recovered?.status === 'failed-verification')
+                return { ...recovered, issue: issue.number };
+            if (activeClaims(comments, actor, key, now()).length > 0)
+                continue;
+            const runnerId = options.runnerId ?? randomUUID();
+            const ttl = flow.spec.workItem.claimTtlSeconds ?? 900;
+            const expiresAt = new Date(now() + ttl * 1000).toISOString();
+            const own = await client.addComment(issue.number, claimBody(flow, issue, runnerId, expiresAt), signal);
+            await delay(flow.spec.workItem.claimSettleMs ?? 1000, signal);
+            comments = await client.listComments(issue.number, signal);
+            const duringClaim = completedBy(flow, comments, actor, key);
+            if (duringClaim)
+                return { status: 'already-completed', issue: issue.number, idempotencyKey: key, externalResultUrl: duringClaim.externalResultUrl };
+            const winner = activeClaims(comments, actor, key, now())[0];
+            if (!winner || winner.comment.id !== own.id) {
+                lostClaim = true;
+                continue;
+            }
+            const stillEligible = (await client.listOpenIssues(requiredLabels, signal)).some(candidate => candidate.number === issue.number);
+            if (!stillEligible) {
+                lostClaim = true;
+                continue;
+            }
+            const runDirectory = path.join(stateRoot, 'runs', `${key}-${Date.now()}`);
+            await fs.mkdir(runDirectory, { recursive: true, mode: 0o700 });
+            const prompt = await fs.readFile(resolveWorkspaceFile(flow, flow.spec.executor.prompt), 'utf8');
+            const startedAt = new Date().toISOString();
+            const execution = await executor.execute({ flow, prompt, issue, idempotencyKey: key, runDirectory, signal });
+            if (execution.exitCode !== 0) {
+                const message = `executor exited with status ${execution.exitCode}`;
+                await writeRunRecord(runDirectory, { job: flow.metadata.name, revision: flow.metadata.revision, issue: issue.number, idempotencyKey: key, startedAt, finishedAt: new Date().toISOString(), exitStatus: execution.exitCode, status: 'failed-verification', message });
+                await writeRecovery(stateRoot, { status: 'failed-verification', issue: issue.number, idempotencyKey: key, message });
+                await client.addComment(issue.number, failureBody(flow, key, message), signal);
+                return { status: 'failed-verification', issue: issue.number, idempotencyKey: key, message };
+            }
+            try {
+                const result = { ...await validateResult(flow, key, execution.finalMessage), issue: issue.number };
+                await writeRunRecord(runDirectory, { job: flow.metadata.name, revision: flow.metadata.revision, issue: issue.number, idempotencyKey: key, startedAt, finishedAt: new Date().toISOString(), exitStatus: execution.exitCode, status: result.status, externalResultUrl: result.externalResultUrl });
+                await writeRecovery(stateRoot, result);
+                await client.addComment(issue.number, completionBody(flow, result), signal);
+                return result;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                await writeRunRecord(runDirectory, { job: flow.metadata.name, revision: flow.metadata.revision, issue: issue.number, idempotencyKey: key, startedAt, finishedAt: new Date().toISOString(), exitStatus: execution.exitCode, status: 'failed-verification', message });
+                await writeRecovery(stateRoot, { status: 'failed-verification', issue: issue.number, idempotencyKey: key, message });
+                await client.addComment(issue.number, failureBody(flow, key, message), signal);
+                return { status: 'failed-verification', issue: issue.number, idempotencyKey: key, message };
+            }
+        }
+        return { status: lostClaim ? 'claim-lost' : 'no-eligible-work' };
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/src/jobs/types.js

@@ -0,0 +1,3 @@
+export const JOB_API_VERSION = 'jobs.aiwg.io/v1';
+export const JOB_KIND = 'ExternalJob';
+//# sourceMappingURL=types.js.map

package/dist/src/providers/capability-matrix.js

@@ -13,6 +13,9 @@ import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { load as loadYaml } from 'js-yaml';
 import { findPackageRoot } from '../cli/find-package-root.js';
+export function isExternalStrategy(strategy) {
+    return strategy === 'external-trigger';
+}
 // ---------------------------------------------------------------------------
 // Loader
 // ---------------------------------------------------------------------------
@@ -257,6 +260,8 @@ export function formatCapabilityTable() {
             if (caps.native_features[f])
                 return padRight('NATIVE', 15);
             const emu = caps.emulation[f];
+            if (isExternalStrategy(emu))
+                return padRight('EXTERNAL', 15);
             if (emu)
                 return padRight(emu, 15);
             return padRight('--', 15);
@@ -264,7 +269,7 @@ export function formatCapabilityTable() {
         lines.push([padRight(caps.display_name, 18), ...cells].join('| '));
     }
     lines.push('');
-    lines.push('Legend: NATIVE = built-in support, aiwg-* = AIWG emulation, -- = unsupported');
+    lines.push('Legend: NATIVE = built-in support, aiwg-* = AIWG emulation, EXTERNAL = host/CI owns the trigger, -- = unsupported');
     return lines.join('\n');
 }
 /**
@@ -287,9 +292,11 @@ export function formatFeatureSupport(feature) {
         const strategy = caps.emulation[feature];
         const status = native
             ? 'NATIVE'
-            : strategy
-                ? `emulated (${strategy})`
-                : 'unsupported';
+            : isExternalStrategy(strategy)
+                ? 'external trigger'
+                : strategy
+                    ? `emulated (${strategy})`
+                    : 'unsupported';
         lines.push(`  ${padRight(caps.display_name, 18)} ${status}`);
     }
     return lines.join('\n');

package/dist/src/providers/capability-matrix.yaml

@@ -16,8 +16,8 @@ providers:
   claude-code:
     display_name: Claude Code
     status: stable
-    daemon_tier: native
-    daemon_pty_adapter: true
+    daemon_tier: unsupported
+    daemon_pty_adapter: false
     artifact_paths:
       agents: .claude/agents/
       commands: .claude/commands/
@@ -31,7 +31,7 @@ providers:
       mcp: true
       behaviors: false
       mission_control: false
-      daemon: true
+      daemon: false
     emulation:
       cron: native
       agent_teams: native
@@ -39,7 +39,7 @@ providers:
       mcp: native
       behaviors: hooks
       mission_control: aiwg-mc
-      daemon: native
+      daemon: null
     hook_wiring:
       at_link_support: true
       hook_file: AIWG.md
@@ -80,8 +80,8 @@ providers:
     aliases:
       - openai
     status: stable
-    daemon_tier: native
-    daemon_pty_adapter: true
+    daemon_tier: unsupported
+    daemon_pty_adapter: false
     artifact_paths:
       agents: .codex/agents/
       commands: "~/.codex/prompts/"
@@ -100,15 +100,15 @@ providers:
       mcp: false
       behaviors: false
       mission_control: false
-      daemon: true
+      daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: external-trigger
       agent_teams: aiwg-mc
       tasks: aiwg-mc
       mcp: null
       behaviors: aiwg-mc
       mission_control: aiwg-mc
-      daemon: native
+      daemon: null
     hook_wiring:
       at_link_support: false
       hook_file: AIWG-codex.md
@@ -164,7 +164,7 @@ providers:
       mission_control: false
       daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: null
       agent_teams: aiwg-mc
       tasks: aiwg-mc
       mcp: null
@@ -183,8 +183,8 @@ providers:
     display_name: Factory AI
     status: stable
     # droid CLI runs headless via `droid exec`; AIWG daemon provides persistence layer
-    daemon_tier: tier1
-    daemon_pty_adapter: true
+    daemon_tier: unsupported
+    daemon_pty_adapter: false
     artifact_paths:
       agents: .factory/droids/
       commands: .factory/commands/
@@ -198,15 +198,15 @@ providers:
       mcp: true               # Native MCP support (stdio + HTTP transports)
       behaviors: false
       mission_control: true   # Factory Missions maps to MC concept
-      daemon: false           # No native persistent daemon; AIWG daemon wraps droid exec
+      daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: null
       agent_teams: null       # native Missions
       tasks: null             # native Task tool
       mcp: null               # native MCP
       behaviors: aiwg-mc
       mission_control: null   # native Missions
-      daemon: aiwg-daemon     # AIWG daemon provides persistence for headless droid exec
+      daemon: null
     hook_wiring:
       at_link_support: false
       hook_file: AIWG-factory.md
@@ -236,7 +236,7 @@ providers:
       mission_control: false
       daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: null
       agent_teams: aiwg-mc
       tasks: aiwg-mc
       mcp: null
@@ -254,7 +254,7 @@ providers:
   opencode:
     display_name: OpenCode
     status: stable
-    daemon_tier: native
+    daemon_tier: unsupported
     daemon_pty_adapter: false
     artifact_paths:
       agents: .opencode/agent/
@@ -269,15 +269,15 @@ providers:
       mcp: false
       behaviors: false
       mission_control: false
-      daemon: true
+      daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: null
       agent_teams: aiwg-mc
       tasks: aiwg-mc
       mcp: null
       behaviors: aiwg-mc
       mission_control: aiwg-mc
-      daemon: native
+      daemon: null
     hook_wiring:
       at_link_support: true
       hook_file: AIWG-opencode.md
@@ -289,7 +289,7 @@ providers:
   warp:
     display_name: Warp Terminal
     status: stable
-    daemon_tier: native
+    daemon_tier: unsupported
     daemon_pty_adapter: false
     artifact_paths:
       agents: .warp/agents/
@@ -305,15 +305,15 @@ providers:
       mcp: false
       behaviors: false
       mission_control: false
-      daemon: true
+      daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: null
       agent_teams: aiwg-mc
       tasks: aiwg-mc
       mcp: null
       behaviors: aiwg-mc
       mission_control: aiwg-mc
-      daemon: native
+      daemon: null
     hook_wiring:
       at_link_support: true
       hook_file: AIWG-warp.md
@@ -344,7 +344,7 @@ providers:
       mission_control: false
       daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: null
       agent_teams: aiwg-mc
       tasks: aiwg-mc
       mcp: null
@@ -362,7 +362,7 @@ providers:
   hermes:
     display_name: Hermes
     status: experimental
-    daemon_tier: native
+    daemon_tier: unsupported
     daemon_pty_adapter: false
     artifact_paths:
       # MCP is OPTIONAL for Hermes (validated v2026.5.13, #1527): it integrates
@@ -382,15 +382,15 @@ providers:
       mcp: true
       behaviors: false
       mission_control: false
-      daemon: true
+      daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: null
       agent_teams: aiwg-mc
       tasks: aiwg-mc
       mcp: native
       behaviors: aiwg-mc
       mission_control: aiwg-mc
-      daemon: native
+      daemon: null
     hook_wiring:
       at_link_support: false
       hook_file: .hermes.md
@@ -402,7 +402,7 @@ providers:
   openclaw:
     display_name: OpenClaw
     status: stable
-    daemon_tier: native
+    daemon_tier: unsupported
     daemon_pty_adapter: false
     artifact_paths:
       agents: "~/.openclaw/agents/"
@@ -417,15 +417,15 @@ providers:
       mcp: true
       behaviors: true
       mission_control: false
-      daemon: true
+      daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: null
       agent_teams: aiwg-mc
       tasks: aiwg-mc
       mcp: native
       behaviors: native
       mission_control: aiwg-mc
-      daemon: native
+      daemon: null
     hook_wiring:
       at_link_support: false
       context_file: "~/.openclaw/config.yaml"
@@ -457,7 +457,7 @@ providers:
       mission_control: false
       daemon: false
     emulation:
-      cron: aiwg-schedule
+      cron: null
       agent_teams: aiwg-mc
       tasks: aiwg-mc
       mcp: null
@@ -477,7 +477,7 @@ features:
     description: Scheduled task execution (recurring triggers)
     native_example: Claude Code CronCreate/CronList/CronDelete tools
     emulation_strategies:
-      aiwg-schedule: AIWG schedule CLI with remote triggers
+      external-trigger: System cron, systemd timers, or CI own time and launch a reviewed provider command
   agent_teams:
     description: Multi-agent orchestration with team coordination
     native_example: Claude Code native agent teams
@@ -505,10 +505,7 @@ features:
       aiwg-mc: AIWG mc start/dispatch/status/watch CLI
   daemon:
     description: >
-      Persistent background process for headless/unattended operation.
-      Tier 1 (native): full daemon support via aiwg daemon start/stop/status.
-      Tier 2 (pty-adapter): PTY bridge for platforms with a TUI but no headless mode.
-      Tier 3 (unsupported): requires a display server or IDE host; daemon not applicable.
-    native_example: aiwg daemon start (Claude Code, OpenCode, Warp, OpenClaw, Codex)
-    emulation_strategies:
-      pty-adapter: node-pty bridge for TUI platforms (Claude Code, Codex secondary mode)
+      Resident AIWG daemon lifecycle. The current production CLI does not expose
+      a daemon command; bundled daemon sources are non-routable development artifacts.
+    native_example: null
+    emulation_strategies: {}