@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/artifact-actions.d.ts

@@ -1,22 +1,26 @@
 /**
- * Artifact action types and validation
- * Ported from agents/halo/cli/pkg/config
+ * Artifact action types and validation.
+ * Ported from agents/halo/cli/pkg/config.
+ *
+ * Artifact actions map tool invocations to artifact labels, allowing agents to
+ * trigger tools automatically when specific artifacts are produced.
  */
+/** A single action that binds a tool invocation to matching artifact labels. */
 export interface ArtifactAction {
     tool: string;
     label: string;
     matches?: string[];
     input?: Record<string, string>;
 }
+/** Agent-level configuration block containing artifact action definitions. */
 export interface AgentArtifactConfig {
     artifact_actions?: ArtifactAction[];
 }
 /**
- * Validate artifact actions configuration
+ * Validate artifact actions configuration.
  * @param actions - List of artifact actions to validate
  * @param httpToolNames - Set of tool names defined in http_tools section
  * @param applicationTools - Set of valid application tool names
  * @returns Array of validation errors (empty if valid)
  */
 export declare function validateArtifactActions(actions: ArtifactAction[], httpToolNames: Set<string>, applicationTools: Set<string>): string[];
-//# sourceMappingURL=artifact-actions.d.ts.map

package/dist/lib/artifact-actions.js

@@ -1,9 +1,12 @@
 /**
- * Artifact action types and validation
- * Ported from agents/halo/cli/pkg/config
+ * Artifact action types and validation.
+ * Ported from agents/halo/cli/pkg/config.
+ *
+ * Artifact actions map tool invocations to artifact labels, allowing agents to
+ * trigger tools automatically when specific artifacts are produced.
  */
 /**
- * Validate artifact actions configuration
+ * Validate artifact actions configuration.
  * @param actions - List of artifact actions to validate
  * @param httpToolNames - Set of tool names defined in http_tools section
  * @param applicationTools - Set of valid application tool names
@@ -38,8 +41,8 @@ export function validateArtifactActions(actions, httpToolNames, applicationTools
     return errors;
 }
 /**
- * Validate template string uses only allowed patterns
- * Only allows {{artifact.X}} and {{preflight.X}} patterns
+ * Validate template string uses only allowed patterns.
+ * Only allows {{artifact.X}} and {{preflight.X}} patterns.
  */
 function validateTemplate(tmpl) {
     const re = /\{\{(\w+)\.(\w+)\}\}/g;
@@ -52,4 +55,3 @@ function validateTemplate(tmpl) {
     }
     return null;
 }
-//# sourceMappingURL=artifact-actions.js.map

package/dist/lib/auto-pull-worker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Detached worker entry point for background sync. See auto-pull.ts for the public API.
+ *
+ * For the system repo: fast-forward pull (safe — repo is read-only locally).
+ * For the user repo + enabled extras: `git fetch` + write a status marker the foreground
+ * CLI surfaces on its next invocation.
+ *
+ * Per-repo lock files at ~/.agents-system/.fetch/<alias>.lock prevent concurrent fetches.
+ * Lock mtime under 5 min => skip (another invocation already in flight).
+ */
+export {};

package/dist/lib/auto-pull-worker.js

@@ -0,0 +1,121 @@
+/**
+ * Detached worker entry point for background sync. See auto-pull.ts for the public API.
+ *
+ * For the system repo: fast-forward pull (safe — repo is read-only locally).
+ * For the user repo + enabled extras: `git fetch` + write a status marker the foreground
+ * CLI surfaces on its next invocation.
+ *
+ * Per-repo lock files at ~/.agents-system/.fetch/<alias>.lock prevent concurrent fetches.
+ * Lock mtime under 5 min => skip (another invocation already in flight).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { simpleGit } from 'simple-git';
+import { tryAutoPull, isGitRepo } from './git.js';
+import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, } from './state.js';
+import { lockFilePath, statusFilePath } from './auto-pull.js';
+const LOCK_TTL_MS = 5 * 60 * 1000;
+function ensureFetchDir() {
+    const dir = path.join(getSystemAgentsDir(), '.fetch');
+    if (!fs.existsSync(dir)) {
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        catch { /* ignore */ }
+    }
+    return dir;
+}
+function tryAcquireLock(alias) {
+    ensureFetchDir();
+    const lock = lockFilePath(alias);
+    try {
+        const stat = fs.statSync(lock);
+        if (Date.now() - stat.mtimeMs < LOCK_TTL_MS)
+            return false;
+    }
+    catch {
+        /* no lock yet */
+    }
+    try {
+        fs.writeFileSync(lock, String(process.pid));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function releaseLock(alias) {
+    try {
+        fs.unlinkSync(lockFilePath(alias));
+    }
+    catch { /* ignore */ }
+}
+function writeStatusMarker(marker) {
+    ensureFetchDir();
+    try {
+        fs.writeFileSync(statusFilePath(marker.alias), JSON.stringify(marker));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+async function notifyRepo(target) {
+    if (!isGitRepo(target.dir))
+        return;
+    const git = simpleGit(target.dir);
+    const remotes = await git.getRemotes(true);
+    const origin = remotes.find((r) => r.name === 'origin');
+    if (!origin?.refs?.fetch)
+        return;
+    await git.fetch('origin');
+    const status = await git.status();
+    if (!status.tracking)
+        return;
+    writeStatusMarker({
+        alias: target.alias,
+        dir: target.dir,
+        ahead: status.ahead ?? 0,
+        behind: status.behind ?? 0,
+        branch: status.tracking,
+        fetchedAt: Date.now(),
+    });
+}
+async function processTarget(target) {
+    if (!tryAcquireLock(target.alias))
+        return;
+    try {
+        if (target.mode === 'pull') {
+            await tryAutoPull(target.dir);
+        }
+        else {
+            await notifyRepo(target);
+        }
+    }
+    catch {
+        /* network / git failures are non-fatal */
+    }
+    finally {
+        releaseLock(target.alias);
+    }
+}
+async function main() {
+    const targets = [];
+    const systemDir = getSystemAgentsDir();
+    if (isGitRepo(systemDir)) {
+        targets.push({ alias: 'system', dir: systemDir, mode: 'pull' });
+    }
+    const userDir = getUserAgentsDir();
+    if (isGitRepo(userDir)) {
+        targets.push({ alias: 'user', dir: userDir, mode: 'notify' });
+    }
+    for (const extra of getEnabledExtraRepos()) {
+        if (isGitRepo(extra.dir)) {
+            targets.push({ alias: extra.alias, dir: extra.dir, mode: 'notify' });
+        }
+    }
+    await Promise.all(targets.map(processTarget));
+}
+main().catch(() => {
+    /* swallow — detached worker must never crash the parent's terminal */
+    process.exit(0);
+});

package/dist/lib/auto-pull.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Background sync for tracked git repos:
+ *   - System repo (~/.agents-system/) is read-only locally — fast-forward auto-pull is safe.
+ *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
+ *     `git fetch` and write a status marker. Next CLI invocation surfaces a one-line
+ *     notice if upstream is ahead. Pulling is left to the user via `agents repo pull`.
+ *
+ * Public API:
+ *   spawnDetachedSync()           — fire-and-forget; never blocks the foreground command.
+ *   printPendingUpdateNotices()   — synchronous; reads markers and prints + consumes them.
+ */
+/** Per-repo lock file path. mtime acts as a recency check. */
+export declare function lockFilePath(alias: string): string;
+/** Per-repo status marker path (for user/extras only). */
+export declare function statusFilePath(alias: string): string;
+export interface FetchStatusMarker {
+    alias: string;
+    dir: string;
+    ahead: number;
+    behind: number;
+    branch: string;
+    fetchedAt: number;
+}
+/** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
+export declare function spawnDetachedSync(): void;
+/**
+ * Read any pending status markers and print one-line notices for repos that
+ * are behind upstream. Markers are deleted after printing so notices don't
+ * repeat on every invocation. Synchronous, cheap (small JSON files).
+ */
+export declare function printPendingUpdateNotices(): void;

package/dist/lib/auto-pull.js

@@ -0,0 +1,97 @@
+/**
+ * Background sync for tracked git repos:
+ *   - System repo (~/.agents-system/) is read-only locally — fast-forward auto-pull is safe.
+ *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
+ *     `git fetch` and write a status marker. Next CLI invocation surfaces a one-line
+ *     notice if upstream is ahead. Pulling is left to the user via `agents repo pull`.
+ *
+ * Public API:
+ *   spawnDetachedSync()           — fire-and-forget; never blocks the foreground command.
+ *   printPendingUpdateNotices()   — synchronous; reads markers and prints + consumes them.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { getSystemAgentsDir } from './state.js';
+/** Where lock files and per-repo status markers live. */
+function fetchStateDir() {
+    return path.join(getSystemAgentsDir(), '.fetch');
+}
+/** Per-repo lock file path. mtime acts as a recency check. */
+export function lockFilePath(alias) {
+    return path.join(fetchStateDir(), `${alias}.lock`);
+}
+/** Per-repo status marker path (for user/extras only). */
+export function statusFilePath(alias) {
+    return path.join(fetchStateDir(), `${alias}.status.json`);
+}
+/** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
+export function spawnDetachedSync() {
+    if (process.env.AGENTS_NO_AUTOPULL === '1')
+        return;
+    // Resolve the worker path relative to the compiled location of this module.
+    // After `tsc`, both files land in the same directory under dist/lib/.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const workerPath = path.join(here, 'auto-pull-worker.js');
+    if (!fs.existsSync(workerPath))
+        return;
+    try {
+        const child = spawn(process.execPath, [workerPath], {
+            detached: true,
+            stdio: 'ignore',
+            env: process.env,
+        });
+        child.unref();
+    }
+    catch {
+        /* best-effort: never break the foreground command */
+    }
+}
+/**
+ * Read any pending status markers and print one-line notices for repos that
+ * are behind upstream. Markers are deleted after printing so notices don't
+ * repeat on every invocation. Synchronous, cheap (small JSON files).
+ */
+export function printPendingUpdateNotices() {
+    const dir = fetchStateDir();
+    if (!fs.existsSync(dir))
+        return;
+    let entries = [];
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (!name.endsWith('.status.json'))
+            continue;
+        const file = path.join(dir, name);
+        let marker = null;
+        try {
+            marker = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch {
+            try {
+                fs.unlinkSync(file);
+            }
+            catch { /* ignore */ }
+            continue;
+        }
+        if (!marker || marker.behind <= 0) {
+            try {
+                fs.unlinkSync(file);
+            }
+            catch { /* ignore */ }
+            continue;
+        }
+        const repoLabel = marker.alias === 'user' ? '~/.agents/' : marker.alias;
+        process.stderr.write(`agents-cli: ${repoLabel} is ${marker.behind} commit${marker.behind === 1 ? '' : 's'} ` +
+            `behind ${marker.branch} — run 'agents repo pull ${marker.alias}' to update.\n`);
+        try {
+            fs.unlinkSync(file);
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/lib/beta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * User-opt-in beta feature flags.
+ *
+ * Preview features live in the git-trackable user repo (~/.agents/agents.yaml)
+ * when present, and otherwise fall back to the local system state file
+ * (~/.agents-system/agents.yaml). This keeps opt-ins portable for users with a
+ * personal agents repo without mixing them into unrelated version capability
+ * checks.
+ */
+import type { BetaFeatureName } from './types.js';
+export declare const ALL_BETA_FEATURES: readonly ["drive", "factory"];
+export declare function getEnabledBetaFeatures(): BetaFeatureName[];
+export declare function isBetaEnabled(feature: BetaFeatureName): boolean;
+export declare function getBetaConfigLocation(): {
+    scope: 'user' | 'system';
+    path: string;
+};
+export declare function setBetaEnabled(features: readonly BetaFeatureName[], enabled: boolean): {
+    scope: 'user' | 'system';
+    path: string;
+    enabledFeatures: BetaFeatureName[];
+};
+export declare function betaEnableHint(feature: BetaFeatureName): string;

package/dist/lib/beta.js

@@ -0,0 +1,90 @@
+/**
+ * User-opt-in beta feature flags.
+ *
+ * Preview features live in the git-trackable user repo (~/.agents/agents.yaml)
+ * when present, and otherwise fall back to the local system state file
+ * (~/.agents-system/agents.yaml). This keeps opt-ins portable for users with a
+ * personal agents repo without mixing them into unrelated version capability
+ * checks.
+ */
+import * as path from 'path';
+import { getAgentsDir, getOptionalUserAgentsDir, readMeta, writeMeta } from './state.js';
+import { readManifest, writeManifest } from './manifest.js';
+export const ALL_BETA_FEATURES = ['drive', 'factory'];
+function isBetaFeatureName(value) {
+    return typeof value === 'string' && ALL_BETA_FEATURES.includes(value);
+}
+function normalizeEnabledFeatures(input) {
+    if (!Array.isArray(input))
+        return [];
+    const seen = new Set();
+    for (const value of input) {
+        if (!isBetaFeatureName(value))
+            continue;
+        seen.add(value);
+    }
+    return [...seen];
+}
+function readUserManifestBeta() {
+    const userAgentsDir = getOptionalUserAgentsDir();
+    if (!userAgentsDir)
+        return null;
+    const manifest = readManifest(userAgentsDir);
+    if (!manifest?.beta)
+        return null;
+    return normalizeEnabledFeatures(manifest.beta.enabled);
+}
+function readSystemMetaBeta() {
+    return normalizeEnabledFeatures(readMeta().beta?.enabled);
+}
+export function getEnabledBetaFeatures() {
+    return readUserManifestBeta() ?? readSystemMetaBeta();
+}
+export function isBetaEnabled(feature) {
+    return getEnabledBetaFeatures().includes(feature);
+}
+export function getBetaConfigLocation() {
+    const userAgentsDir = getOptionalUserAgentsDir();
+    if (userAgentsDir) {
+        return { scope: 'user', path: path.join(userAgentsDir, 'agents.yaml') };
+    }
+    return { scope: 'system', path: path.join(getAgentsDir(), 'agents.yaml') };
+}
+export function setBetaEnabled(features, enabled) {
+    const location = getBetaConfigLocation();
+    const next = new Set(getEnabledBetaFeatures());
+    for (const feature of features) {
+        if (enabled)
+            next.add(feature);
+        else
+            next.delete(feature);
+    }
+    const enabledFeatures = [...next];
+    if (location.scope === 'user') {
+        const userAgentsDir = getOptionalUserAgentsDir();
+        if (!userAgentsDir) {
+            throw new Error('Expected ~/.agents/ to exist while writing beta config.');
+        }
+        const manifest = readManifest(userAgentsDir) ?? {};
+        if (enabledFeatures.length > 0) {
+            manifest.beta = { enabled: enabledFeatures };
+        }
+        else {
+            delete manifest.beta;
+        }
+        writeManifest(userAgentsDir, manifest);
+        return { ...location, enabledFeatures };
+    }
+    const meta = readMeta();
+    if (enabledFeatures.length > 0) {
+        meta.beta = { enabled: enabledFeatures };
+    }
+    else {
+        delete meta.beta;
+    }
+    writeMeta(meta);
+    return { ...location, enabledFeatures };
+}
+export function betaEnableHint(feature) {
+    return `Enable it with: agents beta enable ${feature}`;
+}

package/dist/lib/capabilities.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Capability gate for agent features.
+ *
+ * Every install path that touches an agent-version (hooks, plugins, MCP,
+ * skills, commands) calls `supports(agent, cap, version?)` before writing to
+ * the version's config dir. When the capability is unsupported or the version
+ * is below `since`, the install path skips the write and surfaces a clear
+ * reason instead of silently corrupting an older binary's settings file.
+ */
+import type { AgentId, CapabilityName, CapabilityResult } from './types.js';
+/**
+ * True when the agent supports the capability on at least some version.
+ * Useful for filtering UI lists; does not check installed version.
+ */
+export declare function isCapable(agent: AgentId, cap: CapabilityName): boolean;
+/**
+ * Check whether the given agent (optionally pinned to a specific installed
+ * version) supports `cap`. Pass `version` whenever you know it -- omitting it
+ * only checks the agent-level flag, which is fine for "is this agent ever
+ * capable" filters but NOT for install-time gating.
+ */
+export declare function supports(agent: AgentId, cap: CapabilityName, version?: string): CapabilityResult;
+/**
+ * Human-readable explanation for skipping an install. Stable shape so callers
+ * can either log it or push it onto an `errors[]` collector.
+ */
+export declare function explainSkip(agent: AgentId, cap: CapabilityName, result: CapabilityResult, version?: string): string;
+/** All agents whose `capabilities[cap]` is anything other than `false`. */
+export declare function capableAgents(cap: CapabilityName): AgentId[];

package/dist/lib/capabilities.js

@@ -0,0 +1,74 @@
+/**
+ * Capability gate for agent features.
+ *
+ * Every install path that touches an agent-version (hooks, plugins, MCP,
+ * skills, commands) calls `supports(agent, cap, version?)` before writing to
+ * the version's config dir. When the capability is unsupported or the version
+ * is below `since`, the install path skips the write and surfaces a clear
+ * reason instead of silently corrupting an older binary's settings file.
+ */
+import { AGENTS } from './agents.js';
+/**
+ * Compare semver-like versions ("0.116.0" vs "0.115.9"). Local copy to avoid
+ * importing versions.ts (which imports agents.ts, which imports this file).
+ */
+function compareVersions(a, b) {
+    const aParts = a.split('.').map((n) => parseInt(n, 10) || 0);
+    const bParts = b.split('.').map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const aVal = aParts[i] || 0;
+        const bVal = bParts[i] || 0;
+        if (aVal !== bVal)
+            return aVal - bVal;
+    }
+    return 0;
+}
+function getCapability(agent, cap) {
+    return AGENTS[agent].capabilities[cap];
+}
+/**
+ * True when the agent supports the capability on at least some version.
+ * Useful for filtering UI lists; does not check installed version.
+ */
+export function isCapable(agent, cap) {
+    const c = getCapability(agent, cap);
+    return c !== false;
+}
+/**
+ * Check whether the given agent (optionally pinned to a specific installed
+ * version) supports `cap`. Pass `version` whenever you know it -- omitting it
+ * only checks the agent-level flag, which is fine for "is this agent ever
+ * capable" filters but NOT for install-time gating.
+ */
+export function supports(agent, cap, version) {
+    const c = getCapability(agent, cap);
+    if (c === false)
+        return { ok: false, reason: 'unsupported' };
+    if (c === true)
+        return { ok: true };
+    if (!version)
+        return { ok: true };
+    if (c.since && compareVersions(version, c.since) < 0) {
+        return { ok: false, reason: 'too_old', need: `>= ${c.since}` };
+    }
+    if (c.until && compareVersions(version, c.until) >= 0) {
+        return { ok: false, reason: 'too_new', need: `< ${c.until}` };
+    }
+    return { ok: true };
+}
+/**
+ * Human-readable explanation for skipping an install. Stable shape so callers
+ * can either log it or push it onto an `errors[]` collector.
+ */
+export function explainSkip(agent, cap, result, version) {
+    if (result.ok)
+        return '';
+    const tag = version ? `${agent}@${version}` : agent;
+    if (result.reason === 'unsupported')
+        return `${tag}: ${cap} not supported`;
+    return `${tag}: ${cap} requires ${result.need}`;
+}
+/** All agents whose `capabilities[cap]` is anything other than `false`. */
+export function capableAgents(cap) {
+    return Object.keys(AGENTS).filter((id) => isCapable(id, cap));
+}

package/dist/lib/cloud/codex.d.ts

@@ -1,4 +1,11 @@
-import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions } from './types.js';
+/**
+ * Codex Cloud provider -- wraps the `codex` CLI for cloud dispatch.
+ *
+ * Delegates to `codex cloud exec/status/list` subcommands, parsing their
+ * JSON or text output into the unified CloudTask format. Streaming is
+ * emulated via polling since Codex Cloud lacks an SSE endpoint.
+ */
+import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } from './types.js';
 export declare class CodexCloudProvider implements CloudProvider {
     id: "codex";
     name: string;
@@ -6,7 +13,7 @@ export declare class CodexCloudProvider implements CloudProvider {
     constructor(config?: {
         env?: string;
     });
-    supports(_options: DispatchOptions): boolean;
+    capabilities(): ProviderCapabilities;
     dispatch(options: DispatchOptions): Promise<CloudTask>;
     status(taskId: string): Promise<CloudTask>;
     list(filter?: {
@@ -16,4 +23,3 @@ export declare class CodexCloudProvider implements CloudProvider {
     cancel(_taskId: string): Promise<void>;
     message(_taskId: string, _content: string): Promise<void>;
 }
-//# sourceMappingURL=codex.d.ts.map