Merge pull request #28 from waybarrios/feat/sandbox-policy-contract

Introduce a shared advisory sandbox policy contract for Codex, OpenCode, Claude Code, and Pi
This commit is contained in:
Wayner Barrios
2026-08-17 10:09:05 -04:00
committed by GitHub
9 changed files with 966 additions and 6 deletions
+31
View File
@@ -28,6 +28,7 @@
<a href="#codex-quick-install"><b>Codex Quick Install</b></a> ·
<a href="#pi-quick-install"><b>Pi Quick Install</b></a> ·
<a href="#whats-inside"><b>Skills</b></a> ·
<a href="#sandbox-capability-contract"><b>Sandbox Contract</b></a> ·
<a href="#invocation"><b>Invocation</b></a> ·
<a href="#how-it-works"><b>Architecture</b></a> ·
<a href="#acknowledgments"><b>Credits</b></a>
@@ -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
```
+116 -6
View File
@@ -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 <skill...> [options]
npx @waybarrios/opencode-power-pack install --profile <name> [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 <name> [--json]
npx @waybarrios/opencode-power-pack sandbox resolve --sandbox-profile <name> [--json]
Options:
--profile <name> 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;
});
}
+205
View File
@@ -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.",
],
};
}
+2
View File
@@ -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",
+269
View File
@@ -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"]
}
}
}
+109
View File
@@ -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
}
}
}
}
}
}
+25
View File
@@ -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 });
}
+202
View File
@@ -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/);
});
+7
View File
@@ -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");