@potential-agents/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Potential Agents contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# Potential Agents CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`p-agents` turns a reviewed `potential.md` into a managed Potential Agent revision. The bundle
+contains only logical agent intent; runtime profile IDs, cloud infrastructure, secrets, images,
+and IAM never enter the repository.
+
+## Install
+
+After publication to npm:
+
+```bash
+npm install -g @potential-agents/cli
+p-agents validate
+```
+
+CI should pin the version it executes:
+
+```bash
+npx --yes @potential-agents/cli@0.1.0 validate
+```
+
+## Bundle
+
+```md
+---
+apiVersion: potentialagents/v1alpha1
+id: research-agent
+name: Research Agent
+engine: claude
+model: claude-sonnet-4-6
+tools: [Read, Glob, Grep]
+browser: false
+skills: []
+---
+
+Use evidence and identify uncertainty.
+```
+
+Run `p-agents validate` without credentials. Connected commands require configuration outside
+the bundle:
+
+```bash
+export POTENTIAL_AGENTS_API_URL=https://api.example.com
+export POTENTIAL_AGENTS_ORGANIZATION=org_example
+export POTENTIAL_AGENTS_TOKEN=short_lived_token
+
+p-agents plan
+p-agents apply
+```
+
+`apply` writes `potential.lock`. Commit that generated identity with the reviewed source bundle.
+
+## Architecture
+
+The implementation is intentionally hexagonal:
+
+- `src/domain`: immutable values, invariants and deterministic hashes.
+- `src/application`: SOLID use cases and small ports.
+- `src/adapters`: Commander/terminal inbound adapter plus filesystem, YAML, HTTPS and runtime
+  outbound adapters.
+- `src/composition-root.ts`: the only place concrete adapters are injected.
+
+No application or domain code depends on Commander, Node filesystem APIs, `fetch`, environment
+variables, or cloud SDKs.
+
+## Development
+
+```bash
+npm ci
+npm run typecheck
+npm run build
+npm test
+npm pack --dry-run
+```
+
+The black-box test starts a disposable control-plane fixture and executes the compiled binary. It
+verifies create, readiness, generated lockfile, no-op and run without a real cloud account.
+
+## Releases
+
+Tags in the form `v*` invoke `.github/workflows/publish.yml`. Configure npm Trusted Publishing
+for `shinsekai-dev/potential-agents-cli` and `publish.yml`; the workflow uses GitHub OIDC and has
+no long-lived npm publish token. The first package publication requires the npm scope to have
+been claimed by a maintainer.

package/dist/adapters/outbound/filesystem/bundle-filesystem-repository.d.ts

@@ -0,0 +1,20 @@
+import type { BundleRepository } from '../../../application/ports/bundle-repository.js';
+import { Bundle } from '../../../domain/bundle.js';
+/** Filesystem adapter that parses potential.md and produces deterministic skill hashes. */
+export declare class FilesystemBundleRepository implements BundleRepository {
+    read(root: string): Promise<Bundle>;
+    initialize(root: string, overwrite: boolean): Promise<string>;
+    /** Parses YAML front matter and rejects ambiguous or malformed Markdown documents. */
+    private _parseMarkdown;
+    /** Maps a closed YAML contract to a domain definition. */
+    private _toDefinition;
+    /** Resolves one declared skill directory without allowing an escape from the bundle root. */
+    private _readSkill;
+    /** Lists UTF-8 skill support files in a stable recursive order and rejects symlinks. */
+    private _listFiles;
+    private _readUtf8;
+    private _string;
+    private _number;
+    private _boolean;
+    private _stringArray;
+}

package/dist/adapters/outbound/filesystem/bundle-filesystem-repository.js

@@ -0,0 +1,181 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { basename, relative, resolve, sep } from 'node:path';
+import { parseDocument } from 'yaml';
+import { AgentDefinition } from '../../../domain/agent-definition.js';
+import { Bundle } from '../../../domain/bundle.js';
+import { PotentialAgentsError, validationError } from '../../../domain/errors.js';
+const TEMPLATE = `---
+apiVersion: potentialagents/v1alpha1
+id: my-agent
+name: My Agent
+description: A managed Potential Agent.
+engine: claude
+model: claude-sonnet-4-6
+tools: []
+browser: false
+skills: []
+# limits:
+#   duration_seconds: 300
+#   max_budget_usd: 0.50
+---
+
+Describe the agent's system instructions here.
+`;
+/** Filesystem adapter that parses potential.md and produces deterministic skill hashes. */
+export class FilesystemBundleRepository {
+    async read(root) {
+        const resolvedRoot = resolve(root);
+        const sourcePath = resolve(resolvedRoot, 'potential.md');
+        const source = await this._readUtf8(sourcePath, 'potential.md');
+        const { attributes, instructions } = this._parseMarkdown(source);
+        const definition = this._toDefinition(attributes, instructions);
+        const skills = await Promise.all(definition.skillPaths.map((skillPath) => this._readSkill(resolvedRoot, skillPath)));
+        const names = new Set();
+        for (const skill of skills) {
+            if (names.has(skill.name))
+                throw validationError(`Duplicate skill name "${skill.name}".`);
+            names.add(skill.name);
+        }
+        return new Bundle(resolvedRoot, definition, skills.sort((left, right) => left.path.localeCompare(right.path)));
+    }
+    async initialize(root, overwrite) {
+        const destination = resolve(root, 'potential.md');
+        await mkdir(resolve(root), { recursive: true });
+        try {
+            await stat(destination);
+            if (!overwrite)
+                throw new PotentialAgentsError('FILE_EXISTS', 'potential.md already exists; use --force to overwrite it.');
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT')
+                throw error;
+        }
+        await writeFile(destination, TEMPLATE, { encoding: 'utf8', flag: 'w' });
+        return destination;
+    }
+    /** Parses YAML front matter and rejects ambiguous or malformed Markdown documents. */
+    _parseMarkdown(source) {
+        const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/u.exec(source);
+        if (!match)
+            throw validationError('potential.md must start with YAML front matter delimited by --- lines.');
+        const yaml = parseDocument(match[1] ?? '');
+        if (yaml.errors.length > 0)
+            throw validationError(`Invalid YAML front matter: ${yaml.errors[0]?.message ?? 'unknown error'}`);
+        const content = yaml.toJS();
+        if (content === null || Array.isArray(content) || typeof content !== 'object')
+            throw validationError('YAML front matter must be an object.');
+        return { attributes: content, instructions: match[2] ?? '' };
+    }
+    /** Maps a closed YAML contract to a domain definition. */
+    _toDefinition(attributes, instructions) {
+        const allowed = new Set(['apiVersion', 'id', 'name', 'description', 'engine', 'model', 'tools', 'browser', 'skills', 'limits']);
+        for (const key of Object.keys(attributes)) {
+            if (!allowed.has(key))
+                throw validationError(`Unknown field "${key}" in potential.md.`);
+        }
+        const limitsValue = attributes.limits;
+        if (limitsValue !== undefined && (limitsValue === null || Array.isArray(limitsValue) || typeof limitsValue !== 'object')) {
+            throw validationError('limits must be an object.');
+        }
+        const limitsRecord = (limitsValue ?? {});
+        for (const key of Object.keys(limitsRecord)) {
+            if (!['duration_seconds', 'max_budget_usd'].includes(key))
+                throw validationError(`Unknown limits field "${key}".`);
+        }
+        const tools = this._stringArray(attributes.tools, 'tools');
+        const skills = this._stringArray(attributes.skills, 'skills');
+        const limits = {
+            ...(limitsRecord.duration_seconds === undefined ? {} : { durationSeconds: this._number(limitsRecord.duration_seconds, 'limits.duration_seconds') }),
+            ...(limitsRecord.max_budget_usd === undefined ? {} : { maxBudgetUsd: this._number(limitsRecord.max_budget_usd, 'limits.max_budget_usd') }),
+        };
+        return AgentDefinition.create({
+            apiVersion: this._string(attributes.apiVersion, 'apiVersion'),
+            id: this._string(attributes.id, 'id'),
+            name: this._string(attributes.name, 'name'),
+            ...(attributes.description === undefined ? {} : { description: this._string(attributes.description, 'description') }),
+            engine: this._string(attributes.engine, 'engine'),
+            model: this._string(attributes.model, 'model'),
+            tools,
+            browser: attributes.browser === undefined ? false : this._boolean(attributes.browser, 'browser'),
+            skillPaths: skills,
+            limits,
+            instructions,
+        });
+    }
+    /** Resolves one declared skill directory without allowing an escape from the bundle root. */
+    async _readSkill(root, declaredPath) {
+        if (!declaredPath.trim())
+            throw validationError('Skill paths must be non-blank.');
+        const absolute = resolve(root, declaredPath);
+        const relativePath = relative(root, absolute);
+        if (!relativePath || relativePath === '..' || relativePath.startsWith(`..${sep}`) || relativePath.split(sep).includes('..')) {
+            throw validationError(`Skill path "${declaredPath}" escapes the bundle root.`);
+        }
+        const directory = await lstat(absolute);
+        if (directory.isSymbolicLink())
+            throw validationError(`Skill path "${declaredPath}" may not be a symlink.`);
+        if (!directory.isDirectory())
+            throw validationError(`Skill path "${declaredPath}" must be a directory.`);
+        await stat(resolve(absolute, 'SKILL.md'));
+        const files = await this._listFiles(absolute, root);
+        const hash = createHash('sha256');
+        for (const file of files) {
+            hash.update(relative(root, file).replaceAll('\\', '/'));
+            hash.update('\0');
+            hash.update(await readFile(file));
+            hash.update('\0');
+        }
+        return { path: `./${relativePath.replaceAll('\\', '/')}`, name: basename(absolute), sha256: `sha256:${hash.digest('hex')}`, sourceDirectory: absolute };
+    }
+    /** Lists UTF-8 skill support files in a stable recursive order and rejects symlinks. */
+    async _listFiles(directory, root) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            const absolute = resolve(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw validationError(`Skills may not contain symlinks: ${relative(root, absolute)}.`);
+            if (entry.isDirectory())
+                files.push(...await this._listFiles(absolute, root));
+            else if (entry.isFile())
+                files.push(absolute);
+            else
+                throw validationError(`Unsupported skill entry: ${relative(root, absolute)}.`);
+        }
+        return files;
+    }
+    async _readUtf8(path, label) {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                throw validationError(`${label} is required.`);
+            throw error;
+        }
+    }
+    _string(value, field) {
+        if (typeof value !== 'string')
+            throw validationError(`${field} must be a string.`);
+        return value;
+    }
+    _number(value, field) {
+        if (typeof value !== 'number')
+            throw validationError(`${field} must be a number.`);
+        return value;
+    }
+    _boolean(value, field) {
+        if (typeof value !== 'boolean')
+            throw validationError(`${field} must be a boolean.`);
+        return value;
+    }
+    _stringArray(value, field) {
+        if (value === undefined)
+            return [];
+        if (!Array.isArray(value) || value.some((item) => typeof item !== 'string'))
+            throw validationError(`${field} must be a list of strings.`);
+        return [...value];
+    }
+}
+//# sourceMappingURL=bundle-filesystem-repository.js.map

package/dist/adapters/outbound/filesystem/bundle-filesystem-repository.js.map

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

package/dist/adapters/outbound/filesystem/yaml-lock-repository.d.ts

@@ -0,0 +1,7 @@
+import type { LockRepository } from '../../../application/ports/lock-repository.js';
+import type { PotentialLock } from '../../../domain/lock.js';
+/** Reads and atomically writes the generated potential.lock document. */
+export declare class YamlLockRepository implements LockRepository {
+    read(root: string): Promise<PotentialLock | undefined>;
+    write(root: string, lock: PotentialLock): Promise<void>;
+}

package/dist/adapters/outbound/filesystem/yaml-lock-repository.js

@@ -0,0 +1,64 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parse, stringify } from 'yaml';
+import { PotentialAgentsError } from '../../../domain/errors.js';
+/** Reads and atomically writes the generated potential.lock document. */
+export class YamlLockRepository {
+    async read(root) {
+        const path = resolve(root, 'potential.lock');
+        try {
+            const parsed = parse(await readFile(path, 'utf8'));
+            const agent = parsed.agent;
+            if (parsed.format !== 'potentialagents/lock/v1' || !agent || typeof agent.remote_id !== 'string' || typeof agent.local_id !== 'string' || typeof agent.active_revision !== 'string' || typeof agent.deployment_id !== 'string' || typeof agent.definition_sha256 !== 'string' || typeof agent.status !== 'string') {
+                throw new PotentialAgentsError('LOCK_ERROR', 'potential.lock has an unsupported or incomplete format.');
+            }
+            const skills = Object.fromEntries(Object.entries(parsed.skills ?? {}).map(([pathKey, value]) => {
+                if (typeof value.path !== 'string' || typeof value.skill_id !== 'string' || typeof value.revision !== 'string' || typeof value.sha256 !== 'string') {
+                    throw new PotentialAgentsError('LOCK_ERROR', `potential.lock skill ${pathKey} is incomplete.`);
+                }
+                return [pathKey, { path: value.path, skillId: value.skill_id, revision: value.revision, sha256: value.sha256 }];
+            }));
+            return {
+                format: 'potentialagents/lock/v1',
+                agent: {
+                    localId: agent.local_id,
+                    remoteId: agent.remote_id,
+                    activeRevision: agent.active_revision,
+                    deploymentId: agent.deployment_id,
+                    definitionSha256: agent.definition_sha256,
+                    status: agent.status,
+                },
+                skills,
+            };
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
+    async write(root, lock) {
+        const destination = resolve(root, 'potential.lock');
+        const temporary = resolve(root, `.potential.lock.${randomUUID()}.tmp`);
+        await writeFile(temporary, stringify({
+            format: lock.format,
+            agent: {
+                local_id: lock.agent.localId,
+                remote_id: lock.agent.remoteId,
+                active_revision: lock.agent.activeRevision,
+                deployment_id: lock.agent.deploymentId,
+                definition_sha256: lock.agent.definitionSha256,
+                status: lock.agent.status,
+            },
+            skills: Object.fromEntries(Object.entries(lock.skills).map(([path, skill]) => [path, {
+                    path: skill.path,
+                    skill_id: skill.skillId,
+                    revision: skill.revision,
+                    sha256: skill.sha256,
+                }])),
+        }), 'utf8');
+        await rename(temporary, destination);
+    }
+}
+//# sourceMappingURL=yaml-lock-repository.js.map

package/dist/adapters/outbound/filesystem/yaml-lock-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-lock-repository.js","sourceRoot":"","sources":["../../../../src/adapters/outbound/filesystem/yaml-lock-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAGxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEjE,yEAAyE;AACzE,MAAM,OAAO,kBAAkB;IACtB,KAAK,CAAC,IAAI,CAAC,IAAY;QAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAIhD,CAAC;YACF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YAC3B,IAAI,MAAM,CAAC,MAAM,KAAK,yBAAyB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,eAAe,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAClT,MAAM,IAAI,oBAAoB,CAAC,YAAY,EAAE,yDAAyD,CAAC,CAAC;YAC1G,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE;gBAC7F,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;oBACnJ,MAAM,IAAI,oBAAoB,CAAC,YAAY,EAAE,wBAAwB,OAAO,iBAAiB,CAAC,CAAC;gBACjG,CAAC;gBACD,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;YAClH,CAAC,CAAC,CAAC,CAAC;YACJ,OAAO;gBACL,MAAM,EAAE,yBAAyB;gBACjC,KAAK,EAAE;oBACL,OAAO,EAAE,KAAK,CAAC,QAAQ;oBACvB,QAAQ,EAAE,KAAK,CAAC,SAAS;oBACzB,cAAc,EAAE,KAAK,CAAC,eAAe;oBACrC,YAAY,EAAE,KAAK,CAAC,aAAa;oBACjC,gBAAgB,EAAE,KAAK,CAAC,iBAAiB;oBACzC,MAAM,EAAE,KAAK,CAAC,MAAM;iBACrB;gBACD,MAAM;aACP,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,SAAS,CAAC;YAC3F,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,KAAK,CAAC,IAAY,EAAE,IAAmB;QAClD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QACpD,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,EAAE,mBAAmB,UAAU,EAAE,MAAM,CAAC,CAAC;QACvE,MAAM,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;YACnC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,KAAK,EAAE;gBACL,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO;gBAC5B,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ;gBAC9B,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc;gBAC1C,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY;gBACtC,iBAAiB,EAAE,IAAI,CAAC,KAAK,CAAC,gBAAgB;gBAC9C,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;aAC1B;YACD,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE;oBACnF,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,QAAQ,EAAE,KAAK,CAAC,OAAO;oBACvB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,MAAM,EAAE,KAAK,CAAC,MAAM;iBACrB,CAAC,CAAC,CAAC;SACL,CAAC,EAAE,MAAM,CAAC,CAAC;QACZ,MAAM,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/adapters/outbound/http/http-potential-agents-api.d.ts

@@ -0,0 +1,36 @@
+import type { PotentialAgentsApi, ApiSkillRevision, ApplyAccepted, PlanResult, RemoteAgent } from '../../../application/ports/potential-agents-api.js';
+import type { Bundle, SkillSource } from '../../../domain/bundle.js';
+interface HttpApiOptions {
+    readonly baseUrl: string;
+    readonly accessToken?: string;
+}
+/** HTTPS adapter for the public Potential Agents control-plane contract. */
+export declare class HttpPotentialAgentsApi implements PotentialAgentsApi {
+    private readonly options;
+    private readonly baseUrl;
+    constructor(options: HttpApiOptions);
+    plan(organizationId: string, bundle: Bundle, remoteId?: string): Promise<PlanResult>;
+    uploadSkill(organizationId: string, skill: SkillSource): Promise<ApiSkillRevision>;
+    createAgent(organizationId: string, bundle: Bundle, skills: readonly ApiSkillRevision[], idempotencyKey: string): Promise<ApplyAccepted>;
+    createRevision(organizationId: string, remoteId: string, bundle: Bundle, skills: readonly ApiSkillRevision[], idempotencyKey: string): Promise<ApplyAccepted>;
+    getAgent(organizationId: string, remoteId: string): Promise<RemoteAgent>;
+    createSession(organizationId: string, remoteId: string): Promise<{
+        readonly sessionId: string;
+    }>;
+    createRun(sessionId: string, message: string, idempotencyKey: string): Promise<{
+        readonly runId: string;
+        readonly status: string;
+    }>;
+    archiveAgent(organizationId: string, remoteId: string): Promise<void>;
+    /** Constructs only public logical runtime intent; profile IDs cannot enter this adapter. */
+    private _intent;
+    /** Loads a small, explicit UTF-8 skill directory for the public immutable-skill API. */
+    private _skillContent;
+    /** Sends one authenticated JSON request and converts server failures to safe typed errors. */
+    private _json;
+    private _parseJson;
+    private _errorMessage;
+    private _string;
+    private _remoteAgent;
+}
+export {};

package/dist/adapters/outbound/http/http-potential-agents-api.js

@@ -0,0 +1,150 @@
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { PotentialAgentsError } from '../../../domain/errors.js';
+/** HTTPS adapter for the public Potential Agents control-plane contract. */
+export class HttpPotentialAgentsApi {
+    options;
+    baseUrl;
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = options.baseUrl.replace(/\/$/u, '');
+    }
+    async plan(organizationId, bundle, remoteId) {
+        return this._json('POST', '/v1/managed-agents:plan', {
+            organization_id: organizationId,
+            remote_id: remoteId,
+            definition_sha256: bundle.definitionSha256,
+            intent: this._intent(bundle, []),
+        });
+    }
+    async uploadSkill(organizationId, skill) {
+        const content = await this._skillContent(skill.sourceDirectory);
+        const response = await this._json('POST', '/v1/skills:publish', {
+            organization_id: organizationId,
+            name: skill.name,
+            sha256: skill.sha256,
+            files: content,
+        });
+        return {
+            skillId: this._string(response.skill_id, 'skill_id'),
+            revision: this._string(response.revision, 'revision'),
+            sha256: this._string(response.sha256, 'sha256'),
+        };
+    }
+    async createAgent(organizationId, bundle, skills, idempotencyKey) {
+        const response = await this._json('POST', '/v1/managed-agents', {
+            organization_id: organizationId,
+            definition_sha256: bundle.definitionSha256,
+            ...this._intent(bundle, skills),
+        }, { 'Idempotency-Key': idempotencyKey });
+        return this._remoteAgent(response);
+    }
+    async createRevision(organizationId, remoteId, bundle, skills, idempotencyKey) {
+        const response = await this._json('POST', `/v1/managed-agents/${encodeURIComponent(remoteId)}/revisions`, {
+            definition_sha256: bundle.definitionSha256,
+            ...this._intent(bundle, skills),
+        }, { 'Idempotency-Key': idempotencyKey, 'X-Potential-Organization': organizationId });
+        return this._remoteAgent(response);
+    }
+    async getAgent(organizationId, remoteId) {
+        const response = await this._json('GET', `/v1/managed-agents/${encodeURIComponent(remoteId)}`, undefined, { 'X-Potential-Organization': organizationId });
+        return this._remoteAgent(response);
+    }
+    async createSession(organizationId, remoteId) {
+        const response = await this._json('POST', `/v1/managed-agents/${encodeURIComponent(remoteId)}/sessions`, { organization_id: organizationId });
+        return { sessionId: this._string(response.session_id, 'session_id') };
+    }
+    async createRun(sessionId, message, idempotencyKey) {
+        const response = await this._json('POST', `/v1/sessions/${encodeURIComponent(sessionId)}/runs`, { input: { message, data: null }, metadata: {} }, { 'Idempotency-Key': idempotencyKey });
+        return { runId: this._string(response.run_id, 'run_id'), status: this._string(response.status, 'status') };
+    }
+    async archiveAgent(organizationId, remoteId) {
+        await this._json('DELETE', `/v1/managed-agents/${encodeURIComponent(remoteId)}`, undefined, { 'X-Potential-Organization': organizationId });
+    }
+    /** Constructs only public logical runtime intent; profile IDs cannot enter this adapter. */
+    _intent(bundle, skills) {
+        return {
+            agent: { name: bundle.definition.name, ...(bundle.definition.description ? { description: bundle.definition.description } : {}) },
+            runtime: { engine: bundle.definition.engine, model: bundle.definition.model },
+            behavior: {
+                instructions: bundle.definition.instructions,
+                input_schema: { type: 'object', additionalProperties: true },
+                output_schema: { type: 'object', additionalProperties: true },
+                skills: skills.map((skill) => ({ skill_id: skill.skillId, revision: skill.revision, sha256: skill.sha256 })),
+            },
+            execution: {
+                tools: bundle.definition.tools,
+                browser: bundle.definition.browser,
+                limits: {
+                    ...(bundle.definition.limits.durationSeconds === undefined ? {} : { duration_seconds: bundle.definition.limits.durationSeconds }),
+                    ...(bundle.definition.limits.maxBudgetUsd === undefined ? {} : { max_budget_usd: bundle.definition.limits.maxBudgetUsd }),
+                },
+            },
+        };
+    }
+    /** Loads a small, explicit UTF-8 skill directory for the public immutable-skill API. */
+    async _skillContent(directory, root = directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            const path = resolve(directory, entry.name);
+            const info = await lstat(path);
+            if (info.isSymbolicLink())
+                throw new PotentialAgentsError('VALIDATION_ERROR', `Skills may not contain symlinks: ${relative(root, path)}.`);
+            if (info.isDirectory())
+                files.push(...await this._skillContent(path, root));
+            else if (info.isFile())
+                files.push({ path: relative(root, path).replaceAll('\\', '/'), content: await readFile(path, 'utf8') });
+        }
+        return files;
+    }
+    /** Sends one authenticated JSON request and converts server failures to safe typed errors. */
+    async _json(method, path, body, headers = {}) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                Accept: 'application/json',
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                ...(this.options.accessToken ? { Authorization: `Bearer ${this.options.accessToken}` } : {}),
+                ...headers,
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await response.text();
+        const parsed = text ? this._parseJson(text) : undefined;
+        if (!response.ok) {
+            const message = parsed !== null && typeof parsed === 'object' && 'error' in parsed
+                ? `Potential Agents API returned ${response.status}: ${this._errorMessage(parsed.error)}`
+                : `Potential Agents API returned ${response.status}.`;
+            throw new PotentialAgentsError('API_ERROR', message);
+        }
+        return parsed;
+    }
+    _parseJson(text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new PotentialAgentsError('API_PROTOCOL_ERROR', 'Potential Agents API returned invalid JSON.');
+        }
+    }
+    _errorMessage(error) {
+        if (error !== null && typeof error === 'object' && 'message' in error && typeof error.message === 'string')
+            return error.message;
+        return 'request failed';
+    }
+    _string(value, field) {
+        if (typeof value !== 'string' || !value)
+            throw new PotentialAgentsError('API_PROTOCOL_ERROR', `Potential Agents API response lacks ${field}.`);
+        return value;
+    }
+    _remoteAgent(response) {
+        return {
+            agentId: this._string(response.agent_id, 'agent_id'),
+            activeRevision: this._string(response.active_revision, 'active_revision'),
+            deploymentId: this._string(response.deployment_id, 'deployment_id'),
+            status: this._string(response.status, 'status'),
+        };
+    }
+}
+//# sourceMappingURL=http-potential-agents-api.js.map

package/dist/adapters/outbound/http/http-potential-agents-api.js.map

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

package/dist/adapters/outbound/runtime/sha256-idempotency-key-generator.d.ts

@@ -0,0 +1,5 @@
+import type { IdempotencyKeyGenerator } from '../../../application/ports/idempotency-key-generator.js';
+/** Derives retry-safe idempotency keys from scoped immutable definitions. */
+export declare class Sha256IdempotencyKeyGenerator implements IdempotencyKeyGenerator {
+    generate(organizationId: string, definitionSha256: string, operation: 'create' | 'revision' | 'run'): string;
+}

package/dist/adapters/outbound/runtime/sha256-idempotency-key-generator.js

@@ -0,0 +1,8 @@
+import { createHash } from 'node:crypto';
+/** Derives retry-safe idempotency keys from scoped immutable definitions. */
+export class Sha256IdempotencyKeyGenerator {
+    generate(organizationId, definitionSha256, operation) {
+        return createHash('sha256').update(`${operation}\0${organizationId}\0${definitionSha256}`).digest('hex');
+    }
+}
+//# sourceMappingURL=sha256-idempotency-key-generator.js.map

package/dist/adapters/outbound/runtime/sha256-idempotency-key-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256-idempotency-key-generator.js","sourceRoot":"","sources":["../../../../src/adapters/outbound/runtime/sha256-idempotency-key-generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,6EAA6E;AAC7E,MAAM,OAAO,6BAA6B;IACjC,QAAQ,CAAC,cAAsB,EAAE,gBAAwB,EAAE,SAAwC;QACxG,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,KAAK,cAAc,KAAK,gBAAgB,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3G,CAAC;CACF"}