diff --git a/README.md b/README.md
index b7e0cec..241b041 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@
Codex Quick Install ·
Pi Quick Install ·
Skills ·
+ Sandbox Contract ·
Invocation ·
Architecture ·
Credits
@@ -146,6 +147,27 @@ Profiles automatically include required companion skills and can be combined wit
The npm installer and the full Claude Code/Codex/OpenCode plugins are alternative activation paths. Claude Code users should prefer the namespaced plugin because the selective installer currently targets the portable `.agents/skills` location used by Codex, OpenCode, and Pi. If a full plugin is already active, selectively copying the same skills does not reduce that plugin's loaded catalog.
+## Sandbox Capability Contract
+
+The package assigns every bundled skill a default least-capability profile and an explicit set of allowed escalations. Inspect the complete contract or resolve one skill from the CLI:
+
+```bash
+opencode-power-pack sandbox doctor
+opencode-power-pack sandbox resolve --skill code-review
+opencode-power-pack sandbox resolve --sandbox-profile publish --json
+```
+
+| Sandbox profile | Workspace | Network and credentials | External side effects |
+|---|---|---|---|
+| `observe` | Read | Denied | Denied |
+| `develop` | Write | Denied | Denied |
+| `network-read` | Write | Explicitly approved | Denied |
+| `publish` | Write | Explicitly approved | Explicit confirmation required |
+
+This first contract version reports `advisory` enforcement. It describes the capability boundary that host adapters must enforce, but it does not isolate commands or replace the permissions configured by Codex, Claude Code, OpenCode, or Pi. `sandbox doctor` therefore reports `Backend: not-configured` and `Strict ready: no` instead of implying a stronger guarantee.
+
+Selective installations include a generated `SANDBOX_POLICY.json` beside each copied `SKILL.md`. The file is self-describing and preserves the skill's default profile even when the central package is not present. It remains advisory until an enforcement backend and host adapter are active.
+
## Why This Exists
Claude Code, Codex, OpenCode, and Pi read `SKILL.md` workflows, but many valuable workflows originated as Claude-specific commands and agents. Copying those artifacts directly does not preserve their orchestration, permissions, or subagent behavior.
@@ -453,6 +475,13 @@ opencode-power-pack
+-- package.json
| +-- declares skills/ as a Pi package for pi install
|
++-- sandbox/contract.json
+| +-- maps all fifty-four skills to versioned capability profiles
+| +-- records allowed escalation paths without claiming enforcement
+|
++-- bin/sandbox/policy.mjs
+| +-- validates, resolves, and reports the shared capability contract
+|
+-- .opencode/plugins/opencode-power-pack.js
| +-- registers skills/ in config.skills.paths
| +-- registers code-explorer as a read-only subagent
@@ -480,6 +509,7 @@ The packaged agents deny edits, external network access, and nested tasks. `code
| Portable and host-native subagent orchestration | Proprietary or non-redistributable plugins |
| Licensed adaptations with immutable provenance | Automatic trust of third-party skill catalogs |
| Explicit permission boundaries and regression tests | Supporting OpenCode versions older than 1.18.7 or obsolete Codex plugin formats |
+| Versioned sandbox capability contracts and honest enforcement reporting | Treating advisory metadata as an OS security boundary |
## Contributing
@@ -494,6 +524,7 @@ Before opening a PR:
```bash
npm test
+npm run test:sandbox
npm run smoke:opencode
npm pack --dry-run
```
diff --git a/bin/opencode-power-pack.mjs b/bin/opencode-power-pack.mjs
index b4b85ce..30d7988 100755
--- a/bin/opencode-power-pack.mjs
+++ b/bin/opencode-power-pack.mjs
@@ -11,10 +11,17 @@ import {
readdir,
rename,
rm,
+ writeFile,
} from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
+import {
+ loadSandboxContract,
+ portableSkillPolicy,
+ resolveSandboxProfile,
+ sandboxDoctorReport,
+} from "./sandbox/policy.mjs";
const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const USAGE = `OpenCode Power Pack selective skill installer
@@ -24,6 +31,9 @@ Usage:
npx @waybarrios/opencode-power-pack install [options]
npx @waybarrios/opencode-power-pack install --profile [options]
npx @waybarrios/opencode-power-pack install --all [options]
+ npx @waybarrios/opencode-power-pack sandbox doctor [--json]
+ npx @waybarrios/opencode-power-pack sandbox resolve --skill [--json]
+ npx @waybarrios/opencode-power-pack sandbox resolve --sandbox-profile [--json]
Options:
--profile Install a curated profile. Repeatable.
@@ -119,7 +129,13 @@ export function resolveSelection({ skillNames = [], profileNames = [], all = fal
return [...selected].sort((left, right) => left.localeCompare(right));
}
-async function replaceDirectoryWithRollback(source, destination, force, packageRoot) {
+async function replaceDirectoryWithRollback(
+ source,
+ destination,
+ force,
+ packageRoot,
+ sandboxContract,
+) {
const parent = path.dirname(destination);
const name = path.basename(destination);
const lock = `${destination}.opp-lock`;
@@ -150,6 +166,11 @@ async function replaceDirectoryWithRollback(source, destination, force, packageR
path.join(staged, "THIRD_PARTY_NOTICES.md"),
);
await cp(path.join(packageRoot, "LICENSES"), path.join(staged, "LICENSES"), { recursive: true });
+ await writeFile(
+ path.join(staged, "SANDBOX_POLICY.json"),
+ `${JSON.stringify(portableSkillPolicy(sandboxContract, name), null, 2)}\n`,
+ "utf8",
+ );
if (force && await pathExists(destination)) {
backup = path.join(parent, `.opp-backup-${name}-${randomUUID()}`);
await rename(destination, backup);
@@ -227,6 +248,7 @@ export async function installSkills({
packageRoot = PACKAGE_ROOT,
}) {
if (!dryRun) await mkdir(destination, { recursive: true });
+ const sandboxContract = await loadSandboxContract(packageRoot);
const results = [];
for (const skillName of skillNames) {
@@ -243,7 +265,13 @@ export async function installSkills({
continue;
}
- const warnings = await replaceDirectoryWithRollback(source, target, force, packageRoot);
+ const warnings = await replaceDirectoryWithRollback(
+ source,
+ target,
+ force,
+ packageRoot,
+ sandboxContract,
+ );
results.push({
name: skillName,
status: exists ? "updated" : "installed",
@@ -310,6 +338,82 @@ function printCatalog(catalog, skills, write) {
}
}
+export function parseSandboxArgs(args) {
+ const [command, ...rest] = args;
+ if (!command) throw new Error("Choose a sandbox command: doctor or resolve.");
+ if (!["doctor", "resolve"].includes(command)) {
+ throw new Error(`Unknown sandbox command: ${command}`);
+ }
+
+ const options = { command, json: false };
+ for (let index = 0; index < rest.length; index += 1) {
+ const value = rest[index];
+ if (value === "--json") {
+ options.json = true;
+ } else if (value === "--skill" || value === "--sandbox-profile") {
+ if (command !== "resolve") throw new Error(`${value} is only valid with sandbox resolve.`);
+ const target = rest[index + 1];
+ if (!target || target.startsWith("-")) throw new Error(`${value} requires a value.`);
+ const key = value === "--skill" ? "skillName" : "profileName";
+ if (options[key]) throw new Error(`${value} may be provided only once.`);
+ options[key] = target;
+ index += 1;
+ } else {
+ throw new Error(`Unknown sandbox option: ${value}`);
+ }
+ }
+ if (command === "resolve" && !options.skillName && !options.profileName) {
+ throw new Error("sandbox resolve requires --skill or --sandbox-profile.");
+ }
+ if (command === "resolve" && options.skillName && options.profileName) {
+ throw new Error("Choose exactly one of --skill or --sandbox-profile.");
+ }
+ return options;
+}
+
+function printSandboxResolution(resolution, write) {
+ if (resolution.skill) write(`Skill: ${resolution.skill}\n`);
+ write(`Profile: ${resolution.profile.name}\n`);
+ write(`Description: ${resolution.profile.description}\n`);
+ write(`Risk level: ${resolution.profile.riskLevel}\n`);
+ write(`Enforcement: ${resolution.profile.enforcementLevel}\n`);
+ write("Capabilities:\n");
+ for (const [name, value] of Object.entries(resolution.profile.capabilities)) {
+ write(` ${name.padEnd(20)} ${value}\n`);
+ }
+ if (resolution.allowedEscalations) {
+ const names = resolution.allowedEscalations.map((profile) => profile.name);
+ write(`Allowed escalations: ${names.length > 0 ? names.join(", ") : "none"}\n`);
+ }
+ write("Warning: advisory metadata does not isolate commands or tools.\n");
+}
+
+function printSandboxDoctor(report, write) {
+ write(`Sandbox contract: ${report.ok ? "valid" : "invalid"}\n`);
+ write(`Schema version: ${report.schemaVersion}\n`);
+ write(`Profiles: ${report.profiles}\n`);
+ write(`Assigned skills: ${report.assignedSkills}/${report.packagedSkills}\n`);
+ write(`Enforcement: ${report.enforcementLevel}\n`);
+ write(`Backend: ${report.backend}\n`);
+ write(`Strict ready: ${report.strictReady ? "yes" : "no"}\n`);
+ for (const warning of report.warnings) write(`Warning: ${warning}\n`);
+}
+
+export async function runSandboxCommand(args, context) {
+ const options = parseSandboxArgs(args);
+ const skills = await discoverSkills(context.packageRoot);
+ const availableSkillNames = skills.map((skill) => skill.name);
+ const contract = await loadSandboxContract(context.packageRoot, availableSkillNames);
+ const result = options.command === "doctor"
+ ? sandboxDoctorReport(contract, availableSkillNames)
+ : resolveSandboxProfile(contract, options);
+
+ if (options.json) context.write(`${JSON.stringify(result, null, 2)}\n`);
+ else if (options.command === "doctor") printSandboxDoctor(result, context.write);
+ else printSandboxResolution(result, context.write);
+ return 0;
+}
+
export async function main(args = process.argv.slice(2), context = {}) {
const write = context.write || ((text) => process.stdout.write(text));
const cwd = context.cwd || process.cwd();
@@ -322,6 +426,10 @@ export async function main(args = process.argv.slice(2), context = {}) {
return 0;
}
+ if (command === "sandbox") {
+ return runSandboxCommand(rest, { packageRoot, write });
+ }
+
const catalog = await loadCatalog(packageRoot);
const skills = await discoverSkills(packageRoot);
@@ -372,8 +480,10 @@ export function isDirectInvocation(argvEntry, moduleUrl = import.meta.url) {
const invokedDirectly = isDirectInvocation(process.argv[1]);
if (invokedDirectly) {
- main().catch((error) => {
- process.stderr.write(`Error: ${error.message}\n`);
- process.exitCode = 1;
- });
+ main()
+ .then((exitCode) => { process.exitCode = exitCode; })
+ .catch((error) => {
+ process.stderr.write(`Error: ${error.message}\n`);
+ process.exitCode = 1;
+ });
}
diff --git a/bin/sandbox/policy.mjs b/bin/sandbox/policy.mjs
new file mode 100644
index 0000000..6f95550
--- /dev/null
+++ b/bin/sandbox/policy.mjs
@@ -0,0 +1,205 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+const TOP_LEVEL_KEYS = new Set([
+ "$schema",
+ "schemaVersion",
+ "enforcementLevel",
+ "profiles",
+ "skills",
+]);
+const PROFILE_KEYS = new Set(["description", "riskLevel", "capabilities"]);
+const CAPABILITY_KEYS = new Set([
+ "workspace",
+ "temporaryFiles",
+ "network",
+ "credentials",
+ "externalSideEffects",
+]);
+const ASSIGNMENT_KEYS = new Set(["defaultProfile", "allowedEscalations"]);
+
+function isObject(value) {
+ return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertObject(value, label) {
+ if (!isObject(value)) throw new TypeError(`${label} must be an object.`);
+}
+
+function assertExactKeys(value, expected, label) {
+ for (const key of Object.keys(value)) {
+ if (!expected.has(key)) throw new TypeError(`${label} has unknown field: ${key}`);
+ }
+ for (const key of expected) {
+ if (!Object.hasOwn(value, key)) throw new TypeError(`${label} is missing field: ${key}`);
+ }
+}
+
+function assertChoice(value, choices, label) {
+ if (!choices.includes(value)) {
+ throw new TypeError(`${label} must be one of: ${choices.join(", ")}.`);
+ }
+}
+
+function ownEntry(object, key) {
+ return Object.hasOwn(object, key) ? object[key] : undefined;
+}
+
+export function validateSandboxContract(contract, availableSkillNames) {
+ assertObject(contract, "Sandbox contract");
+ assertExactKeys(contract, TOP_LEVEL_KEYS, "Sandbox contract");
+ if (contract.$schema !== "./contract.schema.json") {
+ throw new TypeError("Sandbox contract must reference ./contract.schema.json.");
+ }
+ if (contract.schemaVersion !== 1) {
+ throw new TypeError(`Unsupported sandbox contract schema version: ${contract.schemaVersion}`);
+ }
+ if (contract.enforcementLevel !== "advisory") {
+ throw new TypeError("PR 1 sandbox contracts must report advisory enforcement.");
+ }
+
+ assertObject(contract.profiles, "Sandbox profiles");
+ const profileEntries = Object.entries(contract.profiles);
+ if (profileEntries.length === 0) throw new TypeError("Sandbox contract must define profiles.");
+ for (const [name, profile] of profileEntries) {
+ if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+ throw new TypeError(`Invalid sandbox profile name: ${name}`);
+ }
+ assertObject(profile, `Sandbox profile ${name}`);
+ assertExactKeys(profile, PROFILE_KEYS, `Sandbox profile ${name}`);
+ if (typeof profile.description !== "string" || profile.description.trim() === "") {
+ throw new TypeError(`Sandbox profile ${name} requires a description.`);
+ }
+ if (!Number.isInteger(profile.riskLevel) || profile.riskLevel < 0) {
+ throw new TypeError(`Sandbox profile ${name} requires a non-negative integer riskLevel.`);
+ }
+ assertObject(profile.capabilities, `Sandbox profile ${name} capabilities`);
+ assertExactKeys(profile.capabilities, CAPABILITY_KEYS, `Sandbox profile ${name} capabilities`);
+ assertChoice(profile.capabilities.workspace, ["read", "write"], `${name}.workspace`);
+ assertChoice(profile.capabilities.temporaryFiles, ["deny", "write"], `${name}.temporaryFiles`);
+ assertChoice(profile.capabilities.network, ["deny", "explicit"], `${name}.network`);
+ assertChoice(profile.capabilities.credentials, ["deny", "explicit"], `${name}.credentials`);
+ assertChoice(
+ profile.capabilities.externalSideEffects,
+ ["deny", "confirm"],
+ `${name}.externalSideEffects`,
+ );
+ }
+
+ assertObject(contract.skills, "Sandbox skill assignments");
+ const assignmentEntries = Object.entries(contract.skills);
+ if (assignmentEntries.length === 0) {
+ throw new TypeError("Sandbox contract must assign skills.");
+ }
+ for (const [skillName, assignment] of assignmentEntries) {
+ if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skillName)) {
+ throw new TypeError(`Invalid sandbox skill name: ${skillName}`);
+ }
+ assertObject(assignment, `Sandbox assignment ${skillName}`);
+ assertExactKeys(assignment, ASSIGNMENT_KEYS, `Sandbox assignment ${skillName}`);
+ const defaultProfile = ownEntry(contract.profiles, assignment.defaultProfile);
+ if (!defaultProfile) {
+ throw new TypeError(`${skillName} references unknown profile: ${assignment.defaultProfile}`);
+ }
+ if (!Array.isArray(assignment.allowedEscalations)) {
+ throw new TypeError(`${skillName}.allowedEscalations must be an array.`);
+ }
+ const seen = new Set();
+ for (const escalationName of assignment.allowedEscalations) {
+ if (typeof escalationName !== "string" || escalationName.trim() === "") {
+ throw new TypeError(`${skillName} has an invalid escalation profile.`);
+ }
+ if (seen.has(escalationName)) {
+ throw new TypeError(`${skillName} repeats escalation profile: ${escalationName}`);
+ }
+ seen.add(escalationName);
+ const escalation = ownEntry(contract.profiles, escalationName);
+ if (!escalation) {
+ throw new TypeError(`${skillName} references unknown escalation: ${escalationName}`);
+ }
+ if (escalationName === assignment.defaultProfile) {
+ throw new TypeError(`${skillName} repeats its default profile as an escalation.`);
+ }
+ if (escalation.riskLevel <= defaultProfile.riskLevel) {
+ throw new TypeError(`${skillName} escalation ${escalationName} must increase riskLevel.`);
+ }
+ }
+ }
+
+ if (availableSkillNames) {
+ const available = new Set(availableSkillNames);
+ const assigned = new Set(Object.keys(contract.skills));
+ const missing = [...available].filter((name) => !assigned.has(name)).sort();
+ const unknown = [...assigned].filter((name) => !available.has(name)).sort();
+ if (missing.length > 0) {
+ throw new TypeError(`Sandbox assignments missing packaged skills: ${missing.join(", ")}`);
+ }
+ if (unknown.length > 0) {
+ throw new TypeError(`Sandbox assignments reference unknown skills: ${unknown.join(", ")}`);
+ }
+ }
+
+ return contract;
+}
+
+export async function loadSandboxContract(packageRoot, availableSkillNames) {
+ const source = await readFile(path.join(packageRoot, "sandbox", "contract.json"), "utf8");
+ return validateSandboxContract(JSON.parse(source), availableSkillNames);
+}
+
+function resolvedProfile(contract, profileName) {
+ const profile = ownEntry(contract.profiles, profileName);
+ if (!profile) throw new Error(`Unknown sandbox profile: ${profileName}`);
+ return {
+ name: profileName,
+ description: profile.description,
+ riskLevel: profile.riskLevel,
+ capabilities: { ...profile.capabilities },
+ enforcementLevel: contract.enforcementLevel,
+ };
+}
+
+export function resolveSandboxProfile(contract, { skillName, profileName }) {
+ if ((skillName ? 1 : 0) + (profileName ? 1 : 0) !== 1) {
+ throw new Error("Choose exactly one of --skill or --sandbox-profile.");
+ }
+ if (profileName) return { profile: resolvedProfile(contract, profileName) };
+
+ const assignment = ownEntry(contract.skills, skillName);
+ if (!assignment) throw new Error(`Unknown sandbox skill: ${skillName}`);
+ return {
+ skill: skillName,
+ profile: resolvedProfile(contract, assignment.defaultProfile),
+ allowedEscalations: assignment.allowedEscalations.map((name) => resolvedProfile(contract, name)),
+ };
+}
+
+export function portableSkillPolicy(contract, skillName) {
+ const resolution = resolveSandboxProfile(contract, { skillName });
+ return {
+ schemaVersion: contract.schemaVersion,
+ source: "@waybarrios/opencode-power-pack",
+ enforcementLevel: contract.enforcementLevel,
+ warning: "This capability policy is advisory until an enforcement backend and host adapter are active.",
+ skill: resolution.skill,
+ profile: resolution.profile,
+ allowedEscalations: resolution.allowedEscalations,
+ };
+}
+
+export function sandboxDoctorReport(contract, availableSkillNames) {
+ validateSandboxContract(contract, availableSkillNames);
+ return {
+ ok: true,
+ schemaVersion: contract.schemaVersion,
+ enforcementLevel: contract.enforcementLevel,
+ backend: "not-configured",
+ strictReady: false,
+ profiles: Object.keys(contract.profiles).length,
+ assignedSkills: Object.keys(contract.skills).length,
+ packagedSkills: availableSkillNames.length,
+ warnings: [
+ "Capability profiles are advisory until an enforcement backend and host adapter are active.",
+ ],
+ };
+}
diff --git a/package.json b/package.json
index 7460f10..d748947 100644
--- a/package.json
+++ b/package.json
@@ -21,6 +21,7 @@
".codex-plugin",
".opencode",
"bin",
+ "sandbox",
"assets",
"skillsets.json",
"UPSTREAMS.json",
@@ -29,6 +30,7 @@
],
"scripts": {
"test": "node --test",
+ "test:sandbox": "node --test tests/sandbox-policy.test.mjs",
"prepublishOnly": "npm test",
"eval:behavioral": "node scripts/behavioral-evals.mjs run",
"eval:behavioral:accept": "node scripts/behavioral-evals.mjs accept",
diff --git a/sandbox/contract.json b/sandbox/contract.json
new file mode 100644
index 0000000..feb86d6
--- /dev/null
+++ b/sandbox/contract.json
@@ -0,0 +1,269 @@
+{
+ "$schema": "./contract.schema.json",
+ "schemaVersion": 1,
+ "enforcementLevel": "advisory",
+ "profiles": {
+ "observe": {
+ "description": "Inspect and analyze the workspace without modifying it or using the network.",
+ "riskLevel": 0,
+ "capabilities": {
+ "workspace": "read",
+ "temporaryFiles": "write",
+ "network": "deny",
+ "credentials": "deny",
+ "externalSideEffects": "deny"
+ }
+ },
+ "develop": {
+ "description": "Modify the workspace and temporary files without network access or external side effects.",
+ "riskLevel": 1,
+ "capabilities": {
+ "workspace": "write",
+ "temporaryFiles": "write",
+ "network": "deny",
+ "credentials": "deny",
+ "externalSideEffects": "deny"
+ }
+ },
+ "network-read": {
+ "description": "Use explicitly approved network destinations and credentials for retrieval without external mutations.",
+ "riskLevel": 2,
+ "capabilities": {
+ "workspace": "write",
+ "temporaryFiles": "write",
+ "network": "explicit",
+ "credentials": "explicit",
+ "externalSideEffects": "deny"
+ }
+ },
+ "publish": {
+ "description": "Perform explicitly confirmed external mutations using narrowly scoped network and credential access.",
+ "riskLevel": 3,
+ "capabilities": {
+ "workspace": "write",
+ "temporaryFiles": "write",
+ "network": "explicit",
+ "credentials": "explicit",
+ "externalSideEffects": "confirm"
+ }
+ }
+ },
+ "skills": {
+ "agentic-actions-auditor": {
+ "defaultProfile": "observe",
+ "allowedEscalations": ["network-read"]
+ },
+ "agents-md-improver": {
+ "defaultProfile": "develop",
+ "allowedEscalations": []
+ },
+ "agents-md-revise": {
+ "defaultProfile": "develop",
+ "allowedEscalations": []
+ },
+ "ai-slop": {
+ "defaultProfile": "observe",
+ "allowedEscalations": []
+ },
+ "code-architect": {
+ "defaultProfile": "observe",
+ "allowedEscalations": []
+ },
+ "code-explorer": {
+ "defaultProfile": "observe",
+ "allowedEscalations": []
+ },
+ "code-quality": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "code-review": {
+ "defaultProfile": "observe",
+ "allowedEscalations": ["network-read", "publish"]
+ },
+ "code-reviewer": {
+ "defaultProfile": "observe",
+ "allowedEscalations": []
+ },
+ "codeql": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "design-patterns": {
+ "defaultProfile": "observe",
+ "allowedEscalations": []
+ },
+ "differential-review": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "feature-dev": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "fp-check": {
+ "defaultProfile": "observe",
+ "allowedEscalations": []
+ },
+ "frontend-design": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "hf-cli": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": ["publish"]
+ },
+ "hf-cloud-aws-context-discovery": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": []
+ },
+ "hf-cloud-python-env-setup": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "hf-cloud-sagemaker-deployment-planner": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": ["publish"]
+ },
+ "hf-cloud-sagemaker-iam-preflight": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": ["publish"]
+ },
+ "hf-cloud-sagemaker-production-defaults": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "hf-cloud-serving-image-selection": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": ["publish"]
+ },
+ "hf-mem": {
+ "defaultProfile": "observe",
+ "allowedEscalations": ["network-read"]
+ },
+ "huggingface-best": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": []
+ },
+ "huggingface-community-evals": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": ["publish"]
+ },
+ "huggingface-datasets": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": ["publish"]
+ },
+ "huggingface-gradio": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read", "publish"]
+ },
+ "huggingface-llm-trainer": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "huggingface-local-models": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": []
+ },
+ "huggingface-lora-space-builder": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "huggingface-paper-publisher": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "huggingface-papers": {
+ "defaultProfile": "network-read",
+ "allowedEscalations": ["publish"]
+ },
+ "huggingface-spaces": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "huggingface-tool-builder": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read", "publish"]
+ },
+ "huggingface-trackio": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "huggingface-vision-trainer": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "huggingface-zerogpu": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "insecure-defaults": {
+ "defaultProfile": "observe",
+ "allowedEscalations": []
+ },
+ "mcp-builder": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "paper-summarizer": {
+ "defaultProfile": "observe",
+ "allowedEscalations": ["network-read"]
+ },
+ "sarif-parsing": {
+ "defaultProfile": "develop",
+ "allowedEscalations": []
+ },
+ "security-review": {
+ "defaultProfile": "observe",
+ "allowedEscalations": ["network-read", "publish"]
+ },
+ "security-threat-model": {
+ "defaultProfile": "develop",
+ "allowedEscalations": []
+ },
+ "semgrep": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "semgrep-rule-creator": {
+ "defaultProfile": "develop",
+ "allowedEscalations": []
+ },
+ "semgrep-rule-variant-creator": {
+ "defaultProfile": "develop",
+ "allowedEscalations": []
+ },
+ "sharp-edges": {
+ "defaultProfile": "observe",
+ "allowedEscalations": []
+ },
+ "skill-creator": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "supply-chain-risk-auditor": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "train-sentence-transformers": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "transformers-js": {
+ "defaultProfile": "develop",
+ "allowedEscalations": ["network-read"]
+ },
+ "trl-training": {
+ "defaultProfile": "publish",
+ "allowedEscalations": []
+ },
+ "variant-analysis": {
+ "defaultProfile": "observe",
+ "allowedEscalations": []
+ },
+ "vuln-report": {
+ "defaultProfile": "observe",
+ "allowedEscalations": ["develop"]
+ }
+ }
+}
diff --git a/sandbox/contract.schema.json b/sandbox/contract.schema.json
new file mode 100644
index 0000000..2447f77
--- /dev/null
+++ b/sandbox/contract.schema.json
@@ -0,0 +1,109 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://github.com/waybarrios/opencode-power-pack/sandbox/contract.schema.json",
+ "title": "OpenCode Power Pack sandbox capability contract",
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "$schema",
+ "schemaVersion",
+ "enforcementLevel",
+ "profiles",
+ "skills"
+ ],
+ "properties": {
+ "$schema": {
+ "const": "./contract.schema.json"
+ },
+ "schemaVersion": {
+ "const": 1
+ },
+ "enforcementLevel": {
+ "const": "advisory"
+ },
+ "profiles": {
+ "type": "object",
+ "minProperties": 1,
+ "propertyNames": {
+ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+ },
+ "additionalProperties": {
+ "$ref": "#/$defs/profile"
+ }
+ },
+ "skills": {
+ "type": "object",
+ "minProperties": 1,
+ "propertyNames": {
+ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+ },
+ "additionalProperties": {
+ "$ref": "#/$defs/skillAssignment"
+ }
+ }
+ },
+ "$defs": {
+ "profile": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["description", "riskLevel", "capabilities"],
+ "properties": {
+ "description": {
+ "type": "string",
+ "minLength": 1
+ },
+ "riskLevel": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "capabilities": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "workspace",
+ "temporaryFiles",
+ "network",
+ "credentials",
+ "externalSideEffects"
+ ],
+ "properties": {
+ "workspace": {
+ "enum": ["read", "write"]
+ },
+ "temporaryFiles": {
+ "enum": ["deny", "write"]
+ },
+ "network": {
+ "enum": ["deny", "explicit"]
+ },
+ "credentials": {
+ "enum": ["deny", "explicit"]
+ },
+ "externalSideEffects": {
+ "enum": ["deny", "confirm"]
+ }
+ }
+ }
+ }
+ },
+ "skillAssignment": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["defaultProfile", "allowedEscalations"],
+ "properties": {
+ "defaultProfile": {
+ "type": "string",
+ "minLength": 1
+ },
+ "allowedEscalations": {
+ "type": "array",
+ "uniqueItems": true,
+ "items": {
+ "type": "string",
+ "minLength": 1
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/tests/package-surface.test.mjs b/tests/package-surface.test.mjs
index 6aa2308..5da75f2 100644
--- a/tests/package-surface.test.mjs
+++ b/tests/package-surface.test.mjs
@@ -6,6 +6,7 @@ import {
existsSync,
mkdirSync,
mkdtempSync,
+ readFileSync,
readdirSync,
rmSync,
writeFileSync,
@@ -52,6 +53,9 @@ test("published package relies on native commands and ships every skill", () =>
"focused review metadata is published",
);
assert.ok(packaged.has("bin/opencode-power-pack.mjs"), "selective installer is published");
+ assert.ok(packaged.has("bin/sandbox/policy.mjs"), "sandbox policy resolver is published");
+ assert.ok(packaged.has("sandbox/contract.json"), "sandbox contract is published");
+ assert.ok(packaged.has("sandbox/contract.schema.json"), "sandbox schema is published");
assert.ok(packaged.has("skillsets.json"), "selective profiles are published");
for (const prefix of ["evals/", "scripts/", "tests/", "docs/superpowers/"]) {
assert.equal(
@@ -121,6 +125,27 @@ test("packed npm artifact exposes a working selective-installer executable", ()
assert.match(output, /Profiles:/);
assert.match(output, /recommended/);
assert.match(output, /code-review/);
+ const sandboxOutput = execFileSync(executable, ["sandbox", "doctor"], {
+ cwd: installRoot,
+ encoding: "utf8",
+ });
+ assert.match(sandboxOutput, /Sandbox contract: valid/);
+ assert.match(sandboxOutput, /Assigned skills: 54\/54/);
+ assert.match(sandboxOutput, /Strict ready: no/);
+ mkdirSync(join(installRoot, ".git"));
+ execFileSync(executable, ["install", "code-review", "--project"], {
+ cwd: installRoot,
+ encoding: "utf8",
+ });
+ const installedPolicy = JSON.parse(
+ readFileSync(
+ join(installRoot, ".agents", "skills", "code-review", "SANDBOX_POLICY.json"),
+ "utf8",
+ ),
+ );
+ assert.equal(installedPolicy.skill, "code-review");
+ assert.equal(installedPolicy.profile.name, "observe");
+ assert.equal(installedPolicy.enforcementLevel, "advisory");
} finally {
rmSync(packedRoot, { recursive: true, force: true });
}
diff --git a/tests/sandbox-policy.test.mjs b/tests/sandbox-policy.test.mjs
new file mode 100644
index 0000000..4487b9e
--- /dev/null
+++ b/tests/sandbox-policy.test.mjs
@@ -0,0 +1,202 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+ discoverSkills,
+ main,
+ parseSandboxArgs,
+} from "../bin/opencode-power-pack.mjs";
+import {
+ loadSandboxContract,
+ portableSkillPolicy,
+ resolveSandboxProfile,
+ sandboxDoctorReport,
+ validateSandboxContract,
+} from "../bin/sandbox/policy.mjs";
+
+const REPO = process.env.REPO || process.cwd();
+
+function clone(value) {
+ return structuredClone(value);
+}
+
+test("sandbox contract covers every packaged skill with four ordered profiles", async () => {
+ const skills = await discoverSkills(REPO);
+ const names = skills.map((skill) => skill.name);
+ const contract = await loadSandboxContract(REPO, names);
+
+ assert.equal(contract.schemaVersion, 1);
+ assert.equal(contract.enforcementLevel, "advisory");
+ assert.deepEqual(Object.keys(contract.profiles), [
+ "observe",
+ "develop",
+ "network-read",
+ "publish",
+ ]);
+ assert.equal(Object.keys(contract.skills).length, names.length);
+ assert.deepEqual(Object.keys(contract.skills).sort(), names);
+ assert.deepEqual(
+ Object.values(contract.profiles).map((profile) => profile.riskLevel),
+ [0, 1, 2, 3],
+ );
+});
+
+test("sandbox assignments preserve required writes and documented external modes", async () => {
+ const contract = await loadSandboxContract(REPO);
+ const expected = {
+ "differential-review": ["develop", ["network-read"]],
+ "security-threat-model": ["develop", []],
+ "supply-chain-risk-auditor": ["develop", ["network-read"]],
+ "security-review": ["observe", ["network-read", "publish"]],
+ "huggingface-community-evals": ["network-read", ["publish"]],
+ "huggingface-datasets": ["network-read", ["publish"]],
+ "huggingface-papers": ["network-read", ["publish"]],
+ "huggingface-tool-builder": ["develop", ["network-read", "publish"]],
+ };
+
+ for (const [skillName, [defaultProfile, allowedEscalations]] of Object.entries(expected)) {
+ assert.deepEqual(contract.skills[skillName], { defaultProfile, allowedEscalations }, skillName);
+ }
+});
+
+test("sandbox JSON schema mirrors the closed top-level contract", async () => {
+ const schema = JSON.parse(
+ await readFile(path.join(REPO, "sandbox", "contract.schema.json"), "utf8"),
+ );
+
+ assert.equal(schema.additionalProperties, false);
+ assert.deepEqual(schema.required, [
+ "$schema",
+ "schemaVersion",
+ "enforcementLevel",
+ "profiles",
+ "skills",
+ ]);
+ assert.equal(schema.properties.schemaVersion.const, 1);
+ assert.equal(schema.properties.enforcementLevel.const, "advisory");
+ assert.equal(schema.$defs.profile.additionalProperties, false);
+ assert.equal(schema.$defs.skillAssignment.additionalProperties, false);
+});
+
+test("sandbox validation rejects unknown fields, incomplete coverage, and unsafe escalations", async () => {
+ const skills = await discoverSkills(REPO);
+ const names = skills.map((skill) => skill.name);
+ const contract = await loadSandboxContract(REPO, names);
+
+ const unknownField = clone(contract);
+ unknownField.unexpected = true;
+ assert.throws(() => validateSandboxContract(unknownField, names), /unknown field: unexpected/);
+
+ const incomplete = clone(contract);
+ delete incomplete.skills[names[0]];
+ assert.throws(() => validateSandboxContract(incomplete, names), /missing packaged skills/);
+
+ const downwardEscalation = clone(contract);
+ downwardEscalation.skills["frontend-design"] = {
+ defaultProfile: "develop",
+ allowedEscalations: ["observe"],
+ };
+ assert.throws(() => validateSandboxContract(downwardEscalation, names), /must increase riskLevel/);
+
+ assert.throws(
+ () => resolveSandboxProfile(contract, { skillName: "__proto__" }),
+ /Unknown sandbox skill/,
+ );
+ assert.throws(
+ () => resolveSandboxProfile(contract, { profileName: "toString" }),
+ /Unknown sandbox profile/,
+ );
+});
+
+test("skill and direct-profile resolution report advisory capabilities explicitly", async () => {
+ const contract = await loadSandboxContract(REPO);
+ const skill = resolveSandboxProfile(contract, { skillName: "code-review" });
+
+ assert.equal(skill.skill, "code-review");
+ assert.equal(skill.profile.name, "observe");
+ assert.equal(skill.profile.enforcementLevel, "advisory");
+ assert.deepEqual(
+ skill.allowedEscalations.map((profile) => profile.name),
+ ["network-read", "publish"],
+ );
+
+ const direct = resolveSandboxProfile(contract, { profileName: "publish" });
+ assert.equal(direct.profile.capabilities.externalSideEffects, "confirm");
+ assert.throws(
+ () => resolveSandboxProfile(contract, { skillName: "code-review", profileName: "observe" }),
+ /exactly one/,
+ );
+});
+
+test("portable policies remain self-describing and never claim enforcement", async () => {
+ const contract = await loadSandboxContract(REPO);
+ const policy = portableSkillPolicy(contract, "huggingface-spaces");
+
+ assert.equal(policy.schemaVersion, 1);
+ assert.equal(policy.skill, "huggingface-spaces");
+ assert.equal(policy.profile.name, "publish");
+ assert.equal(policy.enforcementLevel, "advisory");
+ assert.match(policy.warning, /advisory/i);
+});
+
+test("sandbox doctor reports complete coverage and no configured backend", async () => {
+ const skills = await discoverSkills(REPO);
+ const names = skills.map((skill) => skill.name);
+ const contract = await loadSandboxContract(REPO, names);
+ const report = sandboxDoctorReport(contract, names);
+
+ assert.deepEqual(report, {
+ ok: true,
+ schemaVersion: 1,
+ enforcementLevel: "advisory",
+ backend: "not-configured",
+ strictReady: false,
+ profiles: 4,
+ assignedSkills: 54,
+ packagedSkills: 54,
+ warnings: [
+ "Capability profiles are advisory until an enforcement backend and host adapter are active.",
+ ],
+ });
+});
+
+test("sandbox CLI supports deterministic text and JSON output", async () => {
+ let output = "";
+ const context = {
+ cwd: REPO,
+ home: REPO,
+ packageRoot: REPO,
+ write: (text) => { output += text; },
+ };
+
+ assert.equal(await main(["sandbox", "doctor"], context), 0);
+ assert.match(output, /Assigned skills: 54\/54/);
+ assert.match(output, /Enforcement: advisory/);
+ assert.match(output, /Strict ready: no/);
+
+ output = "";
+ assert.equal(
+ await main(["sandbox", "resolve", "--skill", "code-review", "--json"], context),
+ 0,
+ );
+ const resolution = JSON.parse(output);
+ assert.equal(resolution.skill, "code-review");
+ assert.equal(resolution.profile.name, "observe");
+ assert.equal(resolution.profile.enforcementLevel, "advisory");
+});
+
+test("sandbox CLI parser fails closed on ambiguous and malformed selectors", () => {
+ assert.deepEqual(parseSandboxArgs(["doctor", "--json"]), {
+ command: "doctor",
+ json: true,
+ });
+ assert.throws(() => parseSandboxArgs([]), /doctor or resolve/);
+ assert.throws(() => parseSandboxArgs(["missing"]), /Unknown sandbox command/);
+ assert.throws(() => parseSandboxArgs(["resolve"]), /requires --skill or --sandbox-profile/);
+ assert.throws(
+ () => parseSandboxArgs(["resolve", "--skill", "code-review", "--sandbox-profile", "observe"]),
+ /exactly one/,
+ );
+ assert.throws(() => parseSandboxArgs(["doctor", "--skill", "code-review"]), /only valid/);
+});
diff --git a/tests/selective-installer.test.mjs b/tests/selective-installer.test.mjs
index 13e06a5..17c1ba6 100644
--- a/tests/selective-installer.test.mjs
+++ b/tests/selective-installer.test.mjs
@@ -118,6 +118,13 @@ test("installer copies only selected skills, skips existing skills, and replaces
/Third-Party Notices/,
);
assert.ok((await readdir(path.join(destination, "code-review", "LICENSES"))).length > 0);
+ const sandboxPolicy = JSON.parse(
+ await readFile(path.join(destination, "code-review", "SANDBOX_POLICY.json"), "utf8"),
+ );
+ assert.equal(sandboxPolicy.skill, "code-review");
+ assert.equal(sandboxPolicy.profile.name, "observe");
+ assert.equal(sandboxPolicy.enforcementLevel, "advisory");
+ assert.match(sandboxPolicy.warning, /advisory/i);
const sentinel = path.join(destination, "code-review", "stale.txt");
await writeFile(sentinel, "stale", "utf8");