@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/agent-spec/index.d.ts

@@ -6,17 +6,12 @@ export * from './package-types.js';
 export { parseAgentPackageManifest, loadAgentPackageManifest } from './package-schema.js';
 export { resolveAgentPackage, effectiveResources } from './package-resolve.js';
 export { materializeAgentPackage, sha256OfReceiptFile } from './materialize.js';
-/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
 export declare const AGENT_SPEC_HELP: string;
-/** Resolve a spec (single or comma-list) into concrete installed targets. */
 export declare function resolveAgentTargets(spec: string, opts?: ResolveOptions): AgentTarget[];
-/** Resolve a spec that must name exactly one installed version. */
 export declare function resolveSingleAgentTarget(spec: string, opts?: ResolveOptions): {
     agent: AgentId;
     version: string;
     source: import('./types.js').VersionSource;
 };
-/** Resolve a read/list command's version filter (undefined → all, @default → the default, else concrete). */
 export declare function resolveVersionFilter(agent: AgentId, qualifier: string | undefined | null, opts?: ResolveOptions): VersionFilter;
-/** Concrete version filter for list/display commands (undefined → show all, @default → the default version). */
 export declare function resolveListFilter(agent: AgentId, qualifier: string | undefined | null, opts?: ResolveOptions): string | undefined;

package/dist/lib/agent-spec/index.js

@@ -1,40 +1,26 @@
-// Public API for the agent-spec engine. Commands import from here and get the
-// production provider bound automatically; tests import the pure `./resolve.js`
-// core directly and inject a fake provider.
-//
-// One vocabulary, one resolver, reused by every subcommand that accepts
-// `<agent>[@<qualifier>]`. Built for the hot path: exact / @pinned / bare specs
-// resolve with no directory enumeration; only @latest/@oldest/@all enumerate,
-// via the mtime-cached provider.
 import { defaultVersionProvider } from './provider.js';
 import * as core from './resolve.js';
 export * from './types.js';
 export * from './primitives.js';
-// Portable agent-package resolver + native-home materializer (PHNX-3838).
 export * from './package-types.js';
 export { parseAgentPackageManifest, loadAgentPackageManifest } from './package-schema.js';
 export { resolveAgentPackage, effectiveResources } from './package-resolve.js';
 export { materializeAgentPackage, sha256OfReceiptFile } from './materialize.js';
-/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
 export const AGENT_SPEC_HELP = 'Agent spec: <agent>[@<qualifier>]. Qualifiers: ' +
     '@latest (highest installed), @oldest (lowest installed), ' +
     '@pinned / @default (your configured default — synonyms), ' +
     '@all (every installed version), or an exact @x.y.z. ' +
     'Bare <agent> uses the resolved default (project pin → global default). ' +
     'Comma-separate to combine: claude@all,codex@latest.';
-/** Resolve a spec (single or comma-list) into concrete installed targets. */
 export function resolveAgentTargets(spec, opts = {}) {
     return core.resolveAgentTargets(spec, defaultVersionProvider, opts);
 }
-/** Resolve a spec that must name exactly one installed version. */
 export function resolveSingleAgentTarget(spec, opts = {}) {
     return core.resolveSingleAgentTarget(spec, defaultVersionProvider, opts);
 }
-/** Resolve a read/list command's version filter (undefined → all, @default → the default, else concrete). */
 export function resolveVersionFilter(agent, qualifier, opts = {}) {
     return core.resolveVersionFilter(agent, qualifier, defaultVersionProvider, opts);
 }
-/** Concrete version filter for list/display commands (undefined → show all, @default → the default version). */
 export function resolveListFilter(agent, qualifier, opts = {}) {
     return core.resolveListFilter(agent, qualifier, defaultVersionProvider, opts);
 }

package/dist/lib/agent-spec/materialize.d.ts

@@ -1,13 +1,3 @@
 import type { MaterializationReceipt, MaterializeOptions, ResolvedAgentPackage } from './package-types.js';
-/**
- * Materialize `resolved` into a fresh native home for `options.harness`. Fails
- * closed (throws `AgentPackageError`, writes nothing new) when the harness is
- * not declared supported by the package, or when any effective resource needs
- * a capability the harness+version does not have. Idempotent and
- * deterministic: re-running against the same `outputHome` with the same
- * inputs produces a byte-identical receipt and prunes any managed path this
- * materializer previously wrote that the current resource set no longer needs.
- */
 export declare function materializeAgentPackage(resolved: ResolvedAgentPackage, options: MaterializeOptions): MaterializationReceipt;
-/** Lowercase hex sha256 of arbitrary bytes — exposed for callers that want to verify the receipt file's own digest (Factory's observed-digest record). */
 export declare function sha256OfReceiptFile(receiptPath: string): string;

package/dist/lib/agent-spec/materialize.js

@@ -1,25 +1,3 @@
-/**
- * Native-home materializer (PHNX-3838).
- *
- * `materializeAgentPackage` is the harness-adapter layer: it takes the ONE
- * canonical result `resolveAgentPackage` already decided and projects it into
- * a fresh, isolated native home for one harness (Claude Code, Codex, or
- * OpenCode). It reuses the codebase's existing native-projection primitives
- * instead of re-deriving per-harness format knowledge:
- *
- *   - `agentConfigDirName` / `AGENTS[..].capabilities.rules.file` (agent-spec/agents.ts)
- *     for instructions placement
- *   - `subagentTarget(...)` + its registered transforms (subagents-registry.ts)
- *     for subagent projection
- *   - `writeMcpConfig` (lib/mcp.ts) for per-harness MCP config format
- *   - `registerHooksToSettings` (lib/hooks/install.ts) for per-harness hook
- *     registration, including its stale-registration GC
- *
- * It writes a deterministic, unsigned `materialization-receipt.json` — every
- * `target` path it lists is a path THIS materializer owns, so a second run
- * whose resource set shrank can prune exactly those paths without touching
- * anything else in the output home.
- */
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -63,18 +41,8 @@ function removePath(p) {
             fs.unlinkSync(p);
     }
     catch {
-        /* already gone */
     }
 }
-/**
- * Fail closed: every effective resource's kind must be a supported capability
- * on this harness+version. MCP carries two finer-grained sub-capabilities the
- * coarse `mcp` flag does not cover — `mcpHttp` (remote transport at all) and
- * `mcpHeaders` (custom headers on a remote server) — mirroring the check
- * `registerMcp` already applies (agent-spec/agents.ts). Skipping these let a
- * harness with `mcpHttp: false` (e.g. opencode) or `mcpHeaders: false` (e.g.
- * codex) silently receive an http/sse server or a header it cannot express.
- */
 function assertCapabilitiesSupported(resources, harness, harnessVersion) {
     const unsupported = [];
     for (const r of resources) {
@@ -99,35 +67,12 @@ function assertCapabilitiesSupported(resources, harness, harnessVersion) {
         throw new AgentPackageError(`${harness}@${harnessVersion} cannot materialize this package: ${unsupported.length} unsupported capability request(s)`, 'unsupported-capability', unsupported);
     }
 }
-/**
- * The load-bearing containment invariant: every path this materializer is about
- * to write to (or delete) must, once symlinks in its existing prefix are
- * resolved, stay inside `realOutputHome` (the realpath of the output home). The
- * writers form their targets by APPENDING the harness config dir + resource name
- * to `outputHome` — so a symlink planted at that join point (e.g. an
- * `outputHome/.claude` symlink → the live `~/.claude`) redirects the write
- * outside the output home. `resolveOutputHome`'s front-door guard can't see that
- * child; this check, in the materializer that every writer already funnels
- * through, is what protects a direct (Factory / Prix Cloud) caller too. Called
- * BEFORE any `mkdirSync`/`copyFileSync`/`rmSync`, since `mkdir -p` would happily
- * traverse the symlink first.
- */
 function assertTargetContained(realOutputHome, target, label) {
     const canonical = realpathExistingPrefix(target);
     if (canonical !== realOutputHome && !canonical.startsWith(realOutputHome + path.sep)) {
         throw new AgentPackageError(`${label}: refusing to write outside the output home — '${target}' resolves outside '${realOutputHome}'`, 'path-escape');
     }
 }
-/**
- * The final-leaf guard, stricter than {@link assertTargetContained}: it also
- * refuses a symlink planted AT the leaf itself. `assertTargetContained` resolves
- * an existing leaf symlink and catches it only when the target is outside — but a
- * DANGLING leaf symlink (its target does not exist yet) resolves via the leaf's
- * real parent, reads as contained, and then `copyFileSync`/`writeFileSync`/
- * `chmodSync` FOLLOWS it and creates/overwrites the file at the link's
- * destination. So `lstat` the leaf and reject any symlink outright. Called
- * immediately before each write/chmod of a concrete destination file.
- */
 function assertLeafSafe(realOutputHome, leaf, label) {
     assertTargetContained(realOutputHome, leaf, label);
     let lst;
@@ -135,7 +80,7 @@ function assertLeafSafe(realOutputHome, leaf, label) {
         lst = fs.lstatSync(leaf);
     }
     catch {
-        return; // leaf does not exist — nothing planted
+        return;
     }
     if (lst.isSymbolicLink()) {
         throw new AgentPackageError(`${label}: refusing to write through a symlink at '${leaf}'`, 'path-escape');
@@ -148,9 +93,6 @@ function materializeInstructions(resource, harness, outputHome, realOutputHome)
     }
     const agentDir = path.join(outputHome, agentConfigDirName(harness));
     const destFile = path.join(agentDir, cap.file);
-    // Ancestor guard BEFORE mkdir (else `mkdir -p` traverses a symlinked config
-    // dir into the live home); leaf guard AFTER mkdir (a symlink planted at the
-    // file itself, e.g. on a re-run into a reused home).
     assertTargetContained(realOutputHome, destFile, `${harness} instructions`);
     fs.mkdirSync(path.dirname(destFile), { recursive: true });
     assertLeafSafe(realOutputHome, destFile, `${harness} instructions`);
@@ -171,9 +113,6 @@ function materializeSubagent(resource, harness, outputHome, realOutputHome) {
         throw new AgentPackageError(`${harness} has no subagent target registered`, 'unsupported-capability');
     }
     const dir = target.dir(outputHome);
-    // Ancestor guard BEFORE the write's `mkdir -p` (a symlinked `.claude/agents`
-    // would otherwise be traversed); leaf guard on the concrete subagent file the
-    // writer forms itself, so a preplanted symlink AT that leaf can't redirect it.
     assertTargetContained(realOutputHome, dir, `${harness} subagent '${resource.name}'`);
     fs.mkdirSync(dir, { recursive: true });
     const occupied = target.occupied(dir, resource.name)[0];
@@ -181,19 +120,6 @@ function materializeSubagent(resource, harness, outputHome, realOutputHome) {
     target.write(dir, { name: resource.name, path: resource.sourcePath });
     return path.relative(outputHome, occupied.path);
 }
-/**
- * MCP servers write into one shared per-harness config file that may also
- * carry unrelated content the materializer does not own (an oauth account, a
- * project list — anything the real harness binary writes into that same file
- * once the pod actually runs it). `writeMcpConfig`'s `overwrite` mode already
- * preserves every other top-level key; `allowEmpty: true` is what lets THIS
- * call — which always knows the complete current mcp resource set, including
- * zero — converge the mcp section to exactly that set, rather than the
- * generic path-based pruner deleting the whole file when the package's last
- * mcp resource is removed (that would take the unrelated content with it).
- * Runs whenever the file already exists so a package with zero mcp resources
- * that never wrote one doesn't spuriously create an empty config.
- */
 function materializeMcp(resources, harness, outputHome, realOutputHome) {
     const configPath = getMcpConfigPathForHome(harness, outputHome);
     if (resources.length === 0 && !fs.existsSync(configPath))
@@ -209,9 +135,6 @@ function materializeMcp(resources, harness, outputHome, realOutputHome) {
         headers: r.mcp.headers,
     }));
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    // The shared config is a regular file the materializer (and, later, the harness
-    // itself) rewrites in place; a SYMLINK at that leaf is never something we wrote,
-    // so refuse it before writeMcpConfig follows it out of the output home.
     assertLeafSafe(realOutputHome, configPath, `${harness} mcp config`);
     try {
         writeMcpConfig(harness, configPath, servers, 'overwrite', { allowEmpty: true });
@@ -227,27 +150,14 @@ function materializeHooks(resources, harness, outputHome, realOutputHome) {
     if (resources.length === 0)
         return targets;
     const hooksDir = getHooksDirInHome(harness, outputHome);
-    // Guarding the hooks dir also protects the harness settings.json that
-    // registerHooksToSettings writes below — both live under the same
-    // agent-config-dir ancestor, so a symlink there is caught before either write.
     assertTargetContained(realOutputHome, hooksDir, `${harness} hooks dir`);
     fs.mkdirSync(hooksDir, { recursive: true });
-    // The hooks-dir guard catches a symlinked ANCESTOR, but registerHooksToSettings
-    // (called below) writes a per-harness settings/registrar leaf under that dir's
-    // sibling config root — settings.json, codex hooks.json/config.toml, the
-    // opencode plugin. A symlink planted AT one of those leaves would redirect that
-    // write; fail loud here, before any hook script is copied.
     for (const settingsLeaf of hookRegistrationTargets(harness, outputHome)) {
         assertLeafSafe(realOutputHome, settingsLeaf, `${harness} hook settings`);
     }
     const manifest = {};
     for (const r of resources) {
         const { def, scriptPath } = r.hook;
-        // The hook name is attacker-controlled (it comes from the package's
-        // hooks/*.yaml `name:`) and is used as a filename here — a name like
-        // '../../../.config/foo' would copy + chmod +x OUTSIDE the output home.
-        // Require a single safe path segment AND re-assert containment before the
-        // write, failing loud rather than escaping.
         if (!isSafeSegmentName(r.name)) {
             throw new AgentPackageError(`${harness}: hook name '${r.name}' is not a safe single path segment`, 'invalid-resource');
         }
@@ -256,42 +166,21 @@ function materializeHooks(resources, harness, outputHome, realOutputHome) {
         if (!destScript.startsWith(hooksDirResolved + path.sep)) {
             throw new AgentPackageError(`${harness}: hook '${r.name}' resolves outside the hooks directory`, 'invalid-resource');
         }
-        // The check above is textual (name-traversal); this one refuses a preplanted
-        // symlink AT the script leaf, which both copyFileSync AND chmodSync would
-        // otherwise follow — chmod +x on a file outside the output home.
         assertLeafSafe(realOutputHome, destScript, `${harness} hook '${r.name}'`);
         fs.copyFileSync(scriptPath, destScript);
         fs.chmodSync(destScript, 0o755);
         manifest[r.name] = { script: destScript, events: def.events, matcher: def.matcher, timeout: def.timeout };
         targets.set(r.name, path.relative(outputHome, destScript));
     }
-    // `skipGlobalShimSweep`: this manifest is the PACKAGE's hooks only, so the
-    // default orphan-shim sweep would delete every unrelated `.sh` from the ONE
-    // process-global shim dir (`~/.agents/.cache/shims/hooks/`) — the operator's
-    // real hooks. Materialization is isolated to `outputHome`, so it must never
-    // GC that global directory (PHNX-3838).
     const result = registerHooksToSettings(harness, outputHome, manifest, undefined, { skipGlobalShimSweep: true });
     if (result.errors.length > 0) {
         throw new AgentPackageError(`${harness}: failed to register hook(s) — ${result.errors.join('; ')}`, 'invalid-resource');
     }
     return targets;
 }
-/** Deterministic package ref used in the receipt — `<slug>@<manifest-digest-prefix>`, since packages carry no separate semver here. */
 function packageRef(resolved) {
     return `${resolved.manifest.slug}@${resolved.digest.slice(0, 12)}`;
 }
-/**
- * True when `rel` is a target this pruner may safely delete: a non-empty,
- * `..`-free RELATIVE path whose CANONICAL form (symlinks in its existing prefix
- * resolved) stays strictly inside `realOutputHome`. The receipt is unsigned and
- * sits inside the output home, so a planted receipt could carry a `target` of
- * `../../victim`, `/etc/passwd`, OR an innocuous-looking `skills/keep.txt` sitting
- * one level under a symlinked ancestor (`outputHome/skills` → a victim dir) — a
- * purely textual containment check misses the last shape because `removePath`'s
- * `lstat` only refuses to follow the FINAL component, still traversing symlinked
- * ancestors. Realpath-verify before deleting; skip (never delete) anything that
- * escapes.
- */
 function isSafeContainedTarget(realOutputHome, outputHome, rel) {
     if (typeof rel !== 'string' || rel.length === 0 || rel.includes('\0'))
         return false;
@@ -302,19 +191,15 @@ function isSafeContainedTarget(realOutputHome, outputHome, rel) {
     const canonical = realpathExistingPrefix(path.resolve(outputHome, rel));
     return canonical.startsWith(realOutputHome + path.sep);
 }
-/** Delete any path this materializer owned in a PRIOR run of this exact output home that is no longer part of the current resource set. */
 function pruneStaleManagedPaths(realOutputHome, outputHome, previousTargets, currentTargets) {
     for (const rel of previousTargets) {
         if (currentTargets.has(rel))
             continue;
-        // The prior receipt is unsigned; never delete a target that escapes the
-        // output home — textually OR through a symlinked ancestor.
         if (!isSafeContainedTarget(realOutputHome, outputHome, rel))
             continue;
         removePath(path.join(outputHome, rel));
     }
 }
-/** Structurally validate an untrusted, unsigned prior receipt before its targets are ever trusted for deletion. */
 function isValidReceipt(value) {
     if (!value || typeof value !== 'object')
         return false;
@@ -327,15 +212,12 @@ function isValidReceipt(value) {
 }
 function readPriorReceipt(outputHome) {
     const receiptPath = path.join(outputHome, RECEIPT_FILE);
-    // A preplanted SYMLINK at the receipt is untrusted: reading through it slurps
-    // an arbitrary outside file as the "prior receipt". Treat it as no prior
-    // receipt (the write path refuses to follow it too — see assertLeafSafe below).
     try {
         if (fs.lstatSync(receiptPath).isSymbolicLink())
             return null;
     }
     catch {
-        return null; // no receipt yet
+        return null;
     }
     let parsed;
     try {
@@ -346,15 +228,6 @@ function readPriorReceipt(outputHome) {
     }
     return isValidReceipt(parsed) ? parsed : null;
 }
-/**
- * Materialize `resolved` into a fresh native home for `options.harness`. Fails
- * closed (throws `AgentPackageError`, writes nothing new) when the harness is
- * not declared supported by the package, or when any effective resource needs
- * a capability the harness+version does not have. Idempotent and
- * deterministic: re-running against the same `outputHome` with the same
- * inputs produces a byte-identical receipt and prunes any managed path this
- * materializer previously wrote that the current resource set no longer needs.
- */
 export function materializeAgentPackage(resolved, options) {
     const { harness, harnessVersion, outputHome } = options;
     if (!resolved.manifest.execution.harnesses.supported.includes(harness)) {
@@ -363,15 +236,8 @@ export function materializeAgentPackage(resolved, options) {
     const resources = effectiveResources(resolved, harness);
     assertCapabilitiesSupported(resources, harness, harnessVersion);
     fs.mkdirSync(outputHome, { recursive: true });
-    // The output home now exists, so realpath it once: every write/delete target
-    // is verified against THIS canonical root, so a symlink planted at the
-    // harness-config-dir join point (or a symlinked ancestor named by a stale
-    // receipt) can't redirect a write/delete outside the output home.
     const realOutputHome = fs.realpathSync(outputHome);
     const prior = readPriorReceipt(outputHome);
-    // 'mcp' is excluded: it's a shared config file `materializeMcp` converges
-    // (including to empty) by editing its own section, not a path this generic
-    // delete-by-path pruner may ever remove wholesale — see materializeMcp's doc.
     const previousTargets = new Set((prior?.resources ?? []).filter((r) => r.kind !== 'mcp').map((r) => r.target));
     const entries = [];
     const mcpResources = resources.filter((r) => r.kind === 'mcp');
@@ -402,13 +268,10 @@ export function materializeAgentPackage(resolved, options) {
         warnings: [],
     };
     const receiptPath = path.join(outputHome, RECEIPT_FILE);
-    // Final leaf guard: a symlink planted at the receipt (dangling or live) would
-    // redirect this write out of the output home; refuse it.
     assertLeafSafe(realOutputHome, receiptPath, 'materialization receipt');
     fs.writeFileSync(receiptPath, JSON.stringify(receipt, null, 2) + '\n');
     return receipt;
 }
-/** Lowercase hex sha256 of arbitrary bytes — exposed for callers that want to verify the receipt file's own digest (Factory's observed-digest record). */
 export function sha256OfReceiptFile(receiptPath) {
     return crypto.createHash('sha256').update(fs.readFileSync(receiptPath)).digest('hex');
 }

package/dist/lib/agent-spec/package-resolve.d.ts

@@ -1,12 +1,4 @@
 import type { AgentId } from '../types.js';
 import type { ResolvedAgentPackage, ResolvedResource } from './package-types.js';
-/** Parse, validate, and resolve every declared resource of a package directory into one canonical result. */
 export declare function resolveAgentPackage(packageDir: string): ResolvedAgentPackage;
-/**
- * The resource set a specific harness actually materializes: portable
- * resources, with any harness-overlay resource of the same `(kind, name)`
- * deterministically replacing its portable counterpart, plus overlay-only
- * additions. This is the ONE merge rule every harness adapter shares —
- * `materialize.ts` calls this instead of re-deriving precedence per harness.
- */
 export declare function effectiveResources(resolved: ResolvedAgentPackage, harness: AgentId): ResolvedResource[];

package/dist/lib/agent-spec/package-resolve.js

@@ -1,20 +1,3 @@
-/**
- * Canonical agent-package resolver (PHNX-3838).
- *
- * `resolveAgentPackage` is the ONE place that decides what a package's logical
- * resources are: it validates the manifest, resolves every declared resource
- * path against the package directory (failing closed on anything missing,
- * malformed, or escaping the package root), hashes each resource
- * deterministically, and applies the package's conflict-resolution rule —
- * within one scope (portable, or one harness's overlay) a duplicate
- * `(kind, name)` is a hard validation error; across scopes, an overlay
- * resource deterministically replaces the portable resource of the same
- * `(kind, name)` when a harness materializes it (`effectiveResources`).
- *
- * This module never writes to disk and never knows about any specific
- * harness's native format — `materialize.ts` is the only consumer of
- * `effectiveResources`, and it owns projection, not resolution.
- */
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -22,22 +5,13 @@ import * as yaml from 'yaml';
 import { assertWithin, isSafeSegmentName } from '../paths.js';
 import { loadAgentPackageManifest } from './package-schema.js';
 import { AgentPackageError } from './package-types.js';
-/**
- * Reject a package source that is a symlink, or that resolves (through a
- * symlinked ancestor) outside the package's real root. `assertWithin` above is a
- * TEXTUAL check — `path.resolve` normalizes `..` but never follows links — so a
- * `skills/evil -> /home/user/.ssh` symlink, or an `instructions.md ->
- * /etc/passwd` symlink, passes it while the actual bytes read/copied come from
- * OUTSIDE the package. This is the containment check that makes the copy safe.
- * A missing source is left for the `requireFile`/`requireDir` caller to report.
- */
 function assertRealSourceWithin(abs, packageReal, label) {
     let lst;
     try {
         lst = fs.lstatSync(abs);
     }
     catch {
-        return; // does not exist — requireFile/requireDir reports the specific error
+        return;
     }
     if (lst.isSymbolicLink()) {
         throw new AgentPackageError(`${label}: '${abs}' is a symlink; symlinked package sources are not allowed`, 'path-escape');
@@ -67,7 +41,6 @@ function resolveWithin(containRoot, relPath, label, packageReal) {
 function sha256OfBytes(data) {
     return crypto.createHash('sha256').update(data).digest('hex');
 }
-/** Deterministic combined hash of every file under `dir`, sorted by relative path. */
 function sha256OfDir(dir) {
     const files = [];
     const walk = (base) => {
@@ -171,9 +144,6 @@ function resolveHookResource(packageDir, relPath, provenance, label, packageReal
     if (!hook || typeof hook.name !== 'string' || hook.name.length === 0) {
         throw new AgentPackageError(`${label}: '${relPath}' must declare a 'name'`, 'invalid-resource');
     }
-    // The hook name becomes a filename in the materialized home, so a traversing
-    // name ('../../foo') would write a hook script outside the output home. Reject
-    // anything but a single safe path segment at the source.
     if (!isSafeSegmentName(hook.name)) {
         throw new AgentPackageError(`${label}: hook name '${hook.name}' is not a safe single path segment`, 'invalid-resource');
     }
@@ -217,12 +187,10 @@ function resolveScope(packageDir, paths, provenance, scopeLabel, packageReal) {
         resources.push(resolveMcpResource(packageDir, p, provenance, scopeLabel, packageReal));
     for (const p of paths.hooks)
         resources.push(resolveHookResource(packageDir, p, provenance, scopeLabel, packageReal));
-    // Sort deterministically — resolution order in agent.yaml must not affect output.
     resources.sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind.localeCompare(b.kind)));
     assertNoDuplicates(resources, scopeLabel);
     return resources;
 }
-/** Deterministic package identity digest — independent of which harness later materializes it. */
 function computeDigest(portable, overlays) {
     const hash = crypto.createHash('sha256');
     const record = (label, resources) => {
@@ -234,13 +202,9 @@ function computeDigest(portable, overlays) {
         record(`overlay:${agent}`, overlays[agent] ?? []);
     return hash.digest('hex');
 }
-/** Parse, validate, and resolve every declared resource of a package directory into one canonical result. */
 export function resolveAgentPackage(packageDir) {
     const manifest = loadAgentPackageManifest(packageDir);
     const ex = manifest.execution;
-    // The package's REAL root — every resource source must realpath-resolve under
-    // this, so a symlinked ancestor can't smuggle in bytes from outside. The
-    // manifest already loaded from packageDir, so it exists and realpath succeeds.
     const packageReal = fs.realpathSync(path.resolve(packageDir));
     const portable = resolveScope(packageDir, { instructions: ex.instructions, skills: ex.skills, subagents: ex.subagents, mcp: ex.mcp, hooks: ex.hooks }, 'portable', 'execution', packageReal);
     const overlays = {};
@@ -255,13 +219,6 @@ export function resolveAgentPackage(packageDir) {
         overlays,
     };
 }
-/**
- * The resource set a specific harness actually materializes: portable
- * resources, with any harness-overlay resource of the same `(kind, name)`
- * deterministically replacing its portable counterpart, plus overlay-only
- * additions. This is the ONE merge rule every harness adapter shares —
- * `materialize.ts` calls this instead of re-deriving precedence per harness.
- */
 export function effectiveResources(resolved, harness) {
     const overlay = resolved.overlays[harness] ?? [];
     const overlayKeys = new Set(overlay.map((r) => `${r.kind}:${r.name}`));

package/dist/lib/agent-spec/package-schema.d.ts

@@ -1,5 +1,3 @@
 import type { AgentPackageManifest } from './package-types.js';
-/** Parse and shape-validate the `execution` block of a schema-v3 agent.yaml already read into memory. */
 export declare function parseAgentPackageManifest(raw: unknown, sourceLabel: string): AgentPackageManifest;
-/** Read + parse `<packageDir>/agent.yaml`. Fails closed on missing file or malformed YAML. */
 export declare function loadAgentPackageManifest(packageDir: string): AgentPackageManifest;

package/dist/lib/agent-spec/package-schema.js

@@ -1,12 +1,3 @@
-/**
- * Schema-v3 `execution` block parsing for a portable agent package (agent.yaml).
- *
- * Pure and fs-free beyond reading the manifest file itself — never resolves or
- * hashes referenced resources (that's `package-resolve.ts`). Fails closed on
- * anything malformed: this is the "malformed shared config fails closed"
- * boundary from the PHNX-3838 brief, so a bad manifest throws immediately
- * rather than materializing a partial package.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -43,7 +34,6 @@ function parseHarnessOverlay(raw, agent) {
         hooks: stringArray(r.hooks, `execution.harness_overlays.${agent}.hooks`),
     };
 }
-/** Parse and shape-validate the `execution` block of a schema-v3 agent.yaml already read into memory. */
 export function parseAgentPackageManifest(raw, sourceLabel) {
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
         fail(`${sourceLabel}: expected a YAML mapping at the document root`);
@@ -126,7 +116,6 @@ export function parseAgentPackageManifest(raw, sourceLabel) {
         },
     };
 }
-/** Read + parse `<packageDir>/agent.yaml`. Fails closed on missing file or malformed YAML. */
 export function loadAgentPackageManifest(packageDir) {
     const manifestPath = path.join(packageDir, 'agent.yaml');
     let raw;

package/dist/lib/agent-spec/package-types.d.ts

@@ -1,23 +1,11 @@
-/**
- * Types for the portable agent-package resolver + native-home materializer
- * (PHNX-3838). A package is a filesystem `agent.yaml` (schema v3 `execution`
- * block) describing behavior — instructions, skills, subagents, mcp, hooks —
- * that `resolveAgentPackage` reduces to ONE canonical resource set, which
- * `materializeAgentPackage` then projects into a native Claude Code, Codex, or
- * OpenCode home. See `.agents/plans/phnx-3827-portable-agent-cloud/plan.md`
- * (PR muqsitnawaz/agents#2055) for the source design.
- */
 import type { AgentId } from '../types.js';
 export type PackageResourceKind = 'instructions' | 'skills' | 'subagents' | 'mcp' | 'hooks';
-/** Where a resolved resource came from — the provenance a conflict resolution decision needs. */
 export type ResourceProvenance = 'portable' | 'overlay';
-/** Thrown on any bad package or unsatisfiable materialization request. Never `process.exit`. */
 export declare class AgentPackageError extends Error {
     readonly code: 'invalid-manifest' | 'invalid-resource' | 'duplicate-resource' | 'path-escape' | 'unsupported-harness' | 'unsupported-capability';
     readonly details?: string[] | undefined;
     constructor(message: string, code: 'invalid-manifest' | 'invalid-resource' | 'duplicate-resource' | 'path-escape' | 'unsupported-harness' | 'unsupported-capability', details?: string[] | undefined);
 }
-/** One MCP server declared by a package's `mcp/*.yaml` resource file. */
 export interface PackageMcpServer {
     name: string;
     transport: 'stdio' | 'http' | 'sse';
@@ -27,16 +15,13 @@ export interface PackageMcpServer {
     url?: string;
     headers?: Record<string, string>;
 }
-/** One lifecycle hook declared by a package's `hooks/*.yaml` resource file. */
 export interface PackageHook {
     name: string;
-    /** Path to the hook's script, relative to the hook manifest's own directory. */
     script: string;
     events: string[];
     matcher?: string;
     timeout?: number;
 }
-/** A harness-scoped overlay: the same resource-directory shape as the package root. */
 export interface PackageHarnessOverlay {
     instructions?: string;
     skills?: string[];
@@ -44,7 +29,6 @@ export interface PackageHarnessOverlay {
     mcp?: string[];
     hooks?: string[];
 }
-/** Parsed + shape-validated `execution` block of a schema-v3 `agent.yaml`. */
 export interface AgentPackageManifest {
     schemaVersion: 3;
     name: string;
@@ -64,29 +48,21 @@ export interface AgentPackageManifest {
         harnessOverlays: Partial<Record<AgentId, PackageHarnessOverlay>>;
     };
 }
-/** One resource in the canonical, resolved package — before harness projection. */
 export interface ResolvedResource {
     kind: PackageResourceKind;
-    /** Stable resource name within its kind (skill/subagent/mcp-server/hook name, or 'instructions'). */
     name: string;
-    /** Absolute path to the resource's source — a file for instructions/mcp/hooks, a dir for skills/subagents. */
     sourcePath: string;
-    /** Deterministic content hash — a single file's sha256, or a directory's combined sha256. */
     sha256: string;
     provenance: ResourceProvenance;
-    /** Parsed definition, kind === 'mcp' only. */
     mcp?: PackageMcpServer;
-    /** Parsed definition + resolved script path, kind === 'hooks' only. */
     hook?: {
         def: PackageHook;
         scriptPath: string;
     };
 }
-/** The one canonical resolution of a package: portable resources plus each harness's overlay. */
 export interface ResolvedAgentPackage {
     manifest: AgentPackageManifest;
     packageDir: string;
-    /** Deterministic digest over every declared resource (portable + all overlays), independent of harness. */
     digest: string;
     portable: ResolvedResource[];
     overlays: Partial<Record<AgentId, ResolvedResource[]>>;
@@ -94,7 +70,6 @@ export interface ResolvedAgentPackage {
 export interface MaterializationReceiptEntry {
     kind: PackageResourceKind;
     name: string;
-    /** Path the materializer wrote, relative to the output home. */
     target: string;
     sha256: string;
     provenance: ResourceProvenance;
@@ -114,8 +89,6 @@ export interface MaterializationReceipt {
 }
 export interface MaterializeOptions {
     harness: AgentId;
-    /** Harness version — gates per-kind capability support (e.g. codex hooks need >= 0.116.0). */
     harnessVersion: string;
-    /** Absolute path to the fresh, isolated home to materialize into. Created if missing. */
     outputHome: string;
 }

package/dist/lib/agent-spec/package-types.js

@@ -1,4 +1,3 @@
-/** Thrown on any bad package or unsatisfiable materialization request. Never `process.exit`. */
 export class AgentPackageError extends Error {
     code;
     details;

package/dist/lib/agent-spec/primitives.d.ts

@@ -1,21 +1,3 @@
-/**
- * The only shape a version string may take before it reaches an exec/shim/path
- * boundary. Accepts the literal `latest` or a 1–64 char run of `[A-Za-z0-9._+-]`
- * with no `..` traversal. This is THE validation gate — every resolver funnels
- * exact-version tokens through it.
- */
 export declare const VERSION_RE: RegExp;
-/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
 export declare const AGENT_QUALIFIERS: readonly ["latest", "oldest", "pinned", "default", "all"];
-/**
- * Ordering for version strings (ascending).
- *   1. numeric segment comparison (semver-ish: `2.1.187` > `2.1.143`)
- *   2. tie → trailing `-N` build suffix, numerically (`2026.2.19-2` > `2026.2.19`)
- *   3. still tied → 0 (legacy behavior: `1.0` == `1.0.0`, non-numeric tails == 0)
- *
- * Deliberately NOT a full semver comparator: OpenClaw's `-N` is a rebuild marker
- * (higher = newer); a semver comparator would invert it. The `-N` tiebreak is the
- * only addition over the historical numeric-only compare, so suffix-free versions
- * (claude/codex semver) are unaffected.
- */
 export declare function compareVersions(a: string, b: string): number;