an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
fix(hires): enforce runtime allowlists in gallery validator
HaningZS971154807fb8
diff --git a/docs/hires/spec/HIRE_SPEC.md b/docs/hires/spec/HIRE_SPEC.mdindex d2b1c8d4..9c8ada55 100644--- a/docs/hires/spec/HIRE_SPEC.md+++ b/docs/hires/spec/HIRE_SPEC.md@@ -20,6 +20,8 @@ and imported into anyone's office with one click."model": "claude-sonnet-4-6","commandFlags": ["--max-turns", "80"],"capabilities": ["docs", "writing", "markdown"],+ "skills": ["md-audit"],+ "mcpServers": ["fetch"],"isolate": false,"tokenCap": 2000000,"author": "Jason Choplin",@@ -46,16 +48,24 @@ A manifest is untrusted input. The format is designed so it **cannot**:- **Auto-spawn an agent.** Import only pre-fills the form. A human reviews every field —the modal shows an "imported" banner — and clicks spawn.- **Name an executable.** There is no `command` field. The spawn binary always comes from the- user's locally configured provider preset (`claude`, `agy`, `codex`). `provider: "custom"`+ user's locally configured provider preset (`claude`, `agy`, `codex`, `cursor`). `provider: "custom"`is rejected.-- **Smuggle shell syntax.** `commandFlags` entries must match `^[A-Za-z0-9._/=:,@%+-]{1,100}$`- (no quotes, whitespace, semicolons, pipes, backticks), the first entry must be flag-shaped- (`-…`), and args are passed to node-pty as argv — never through a shell.+- **Select arbitrary CLI behavior.** `commandFlags` is default-deny. Only `--model`,+ `--max-turns`, `--output-format`, and `--verbose` are accepted, either as+ `--flag value` or `--flag=value`. A bare value may only immediately follow an allowed+ split-form flag. Every token must also match the conservative character set+ `^[A-Za-z0-9._/=:,@+-]{1,100}$`; quotes, whitespace, percent expansion, and shell+ metacharacters are rejected. Args are passed to node-pty as argv, never through a shell.+- **Name arbitrary skills or MCP processes.** `skills` and `mcpServers` contain ids from+ the app's bundled allowlists, never paths, package names, commands, environment variables,+ or raw MCP specs. MCP entries that need write access or secrets require explicit consent+ during import and are never auto-enabled.- **Be oversized or off-origin.** 64 KB cap, https-only fetch, every string field length-capped.-Things a manifest *can* legitimately influence that you should still eyeball before spawning:-flags like `--permission-mode` change how autonomously the agent runs, and `goal` is prompt-text the agent will act on. That's exactly why import never skips the review step.+The safe flags still influence model selection, turn limits, output shape, or verbosity, and+`goal` is prompt text the agent will act on. Review them before spawning. Permission, sandbox,+approval, provider/backend, configuration, MCP, and prompt-injection flags are intentionally+not shareable; add an exceptional flag by hand after import if you trust and need it.## Field reference@@ -67,14 +77,16 @@ text the agent will act on. That's exactly why import never skips the review ste| `goal` | string ≤ 4000 | | standing mission text || `character` | string ≤ 24 | | office cast id; unknown → default sprite || `accent` | string ≤ 24 | | color name; unknown → default |-| `provider` | `claude` \| `antigravity` \| `agy` \| `codex` | | `agy` = alias for `antigravity`; omit = user default |+| `provider` | `claude` \| `antigravity` \| `agy` \| `codex` \| `cursor` | | `agy` = alias for `antigravity`; omit = user default || `model` | string ≤ 80 | | provider model id/label |-| `commandFlags` | string[] ≤ 16 | | flag-shaped tokens appended to the locally-built command |+| `commandFlags` | string[] ≤ 16 | | allowlisted safe flags and their immediately following values || `capabilities` | string[] ≤ 12 | | hive routing tags || `isolate` | boolean | | spawn in own git worktree || `tokenCap` | int 1…1e10 | | per-agent token budget || `author` | string ≤ 80 | | attribution || `homepage` | string ≤ 300 | | https only |+| `skills` | bundled skill id[] ≤ 8 | | built-in safe skills only; no paths or arbitrary ids |+| `mcpServers` | MCP catalog id[] ≤ 8 | | built-in catalog only; write/secret tiers require consent |## Conventionsdiff --git a/docs/hires/spec/hire.schema.json b/docs/hires/spec/hire.schema.jsonindex ae11d0ab..06d4f49a 100644--- a/docs/hires/spec/hire.schema.json+++ b/docs/hires/spec/hire.schema.json@@ -40,7 +40,7 @@"examples": ["mint"]},"provider": {- "enum": ["claude", "antigravity", "agy", "codex"],+ "enum": ["claude", "antigravity", "agy", "codex", "cursor"],"description": "Which CLI the role is designed for. 'agy' is an alias for 'antigravity'. 'custom' is deliberately not allowed — a manifest can never choose an arbitrary local binary."},"model": {@@ -54,9 +54,9 @@"maxItems": 16,"items": {"type": "string",- "pattern": "^[A-Za-z0-9._/=:,@%+-]{1,100}$"+ "pattern": "^(?=.{1,100}$)(?:--(?:model|max-turns|output-format|verbose)(?:=[A-Za-z0-9._/=:,@+-]*)?|[A-Za-z0-9._/=:,@+][A-Za-z0-9._/=:,@+-]*)$"},- "description": "Extra flag-shaped args appended to the LOCALLY-built spawn command (the binary always comes from the user's provider preset). The first entry must start with '-'. No quotes, whitespace, or shell metacharacters; args are passed as argv, never through a shell."+ "description": "Extra args appended to the LOCALLY-built spawn command (the binary always comes from the user's provider preset). Flag tokens are default-deny: only --model, --max-turns, --output-format, and --verbose are allowed, in split or --flag=value form. A bare value may only immediately follow an allowed split-form flag; this positional rule is enforced by the runtime and browser validators because JSON Schema draft-07 cannot express it. No quotes, whitespace, percent expansion, or shell metacharacters."},"capabilities": {"type": "array",diff --git a/docs/hires/validator.js b/docs/hires/validator.jsindex 13f4dc21..bcacb22a 100644--- a/docs/hires/validator.js+++ b/docs/hires/validator.js@@ -8,6 +8,15 @@ window.HireSpec = (function () {const PROVIDERS = ['claude', 'antigravity', 'codex', 'cursor'];const PROVIDER_LABEL = { claude: 'Claude Code', antigravity: 'Antigravity', codex: 'Codex', cursor: 'Cursor' };const FLAG_RE = /^[A-Za-z0-9._\/=:,@+-]{1,100}$/;+ // Keep these allowlists in lockstep with src/shared/hire.ts and+ // src/shared/mcpCatalog.ts. test/hire-validator-parity.test.cjs locks the+ // browser validator to the canonical runtime validator.+ const SAFE_FLAG_NAMES = new Set(['--model', '--max-turns', '--output-format', '--verbose']);+ const BUNDLED_SKILL_IDS = new Set(['md-hive-sync', 'md-fetch-summarize', 'md-audit']);+ const MCP_SERVER_IDS = new Set([+ 'sequential-thinking', 'time', 'fetch', 'context7', 'filesystem', 'git',+ 'github-token', 'db', 'email-calendar', 'search-with-key'+ ]);// model flows onto the spawn command line — reject shell metacharacters// (mirror of MODEL_RE in the app's src/shared/hire.ts).const MODEL_RE = /^[A-Za-z0-9 ._()[\]\/:@+-]{1,80}$/;@@ -16,6 +25,10 @@ window.HireSpec = (function () {const ACCENTS = ['coral', 'mint', 'sky', 'lemon', 'lilac', 'peach'];function normalizeProvider(p) { return p === 'agy' ? 'antigravity' : p; }+ function isSafeFlag(token) {+ if (!token.startsWith('-')) return false;+ return SAFE_FLAG_NAMES.has(token.split('=', 1)[0].toLowerCase());+ }function validate(raw) {const errors = [];@@ -49,12 +62,59 @@ window.HireSpec = (function () {if (!Array.isArray(raw.commandFlags) || raw.commandFlags.length > 16) {errors.push('"commandFlags" must be an array of at most 16 items');} else {- raw.commandFlags.forEach((f) => {- if (!str(f) || !FLAG_RE.test(f)) errors.push('commandFlags entry ' + JSON.stringify(f) + ' is not a safe flag token');+ let valueAllowed = false;+ raw.commandFlags.forEach((f, index) => {+ if (!str(f) || !FLAG_RE.test(f)) {+ errors.push('commandFlags entry ' + JSON.stringify(f) + ' is not a safe flag token');+ valueAllowed = false;+ return;+ }+ if (index === 0 && !f.startsWith('-')) {+ errors.push('"commandFlags" must start with a flag (e.g. "--model")');+ valueAllowed = false;+ return;+ }+ if (f.startsWith('-')) {+ if (!isSafeFlag(f)) {+ errors.push('commandFlags entry ' + JSON.stringify(f) + ' is not in the shared-hire safe-flag list (' + Array.from(SAFE_FLAG_NAMES).join(', ') + ')');+ valueAllowed = false;+ return;+ }+ valueAllowed = !f.includes('=');+ } else {+ if (!valueAllowed) {+ errors.push('commandFlags entry ' + JSON.stringify(f) + ' is not allowed here (a value may only follow an allowed flag such as "--model")');+ return;+ }+ valueAllowed = false;+ }+ });+ }+ }+ if (raw.skills !== undefined) {+ if (!Array.isArray(raw.skills) || raw.skills.length > 8) {+ errors.push('"skills" must be an array of at most 8 items');+ } else {+ raw.skills.forEach((skill) => {+ if (!str(skill) || !skill.trim()) {+ errors.push('"skills" entries must be non-empty strings');+ } else if (!BUNDLED_SKILL_IDS.has(skill.trim())) {+ errors.push('"skills" entry ' + JSON.stringify(skill.trim()) + ' is not a bundled skill id');+ }+ });+ }+ }+ if (raw.mcpServers !== undefined) {+ if (!Array.isArray(raw.mcpServers) || raw.mcpServers.length > 8) {+ errors.push('"mcpServers" must be an array of at most 8 items');+ } else {+ raw.mcpServers.forEach((server) => {+ if (!str(server) || !server.trim()) {+ errors.push('"mcpServers" entries must be non-empty strings');+ } else if (!MCP_SERVER_IDS.has(server.trim())) {+ errors.push('"mcpServers" entry ' + JSON.stringify(server.trim()) + ' is not a known catalog id');+ }});- if (raw.commandFlags.length && str(raw.commandFlags[0]) && !raw.commandFlags[0].startsWith('-')) {- errors.push('"commandFlags" must start with a flag (e.g. "--max-turns")');- }}}if (raw.capabilities !== undefined && (!Array.isArray(raw.capabilities) || raw.capabilities.length > 12)) {@@ -64,7 +124,7 @@ window.HireSpec = (function () {if (raw.tokenCap !== undefined && !(Number.isInteger(raw.tokenCap) && raw.tokenCap > 0 && raw.tokenCap <= 1e10)) {errors.push('"tokenCap" must be a positive integer (max 1e10)');}- if (str(raw.homepage) && raw.homepage && !raw.homepage.startsWith('https://')) errors.push('"homepage" must be https');+ if (str(raw.homepage) && raw.homepage.trim() && !raw.homepage.trim().startsWith('https://')) errors.push('"homepage" must be https');return { ok: errors.length === 0, errors };}diff --git a/test/hire-validator-parity.test.cjs b/test/hire-validator-parity.test.cjsnew file mode 100644index 00000000..f06f602c--- /dev/null+++ b/test/hire-validator-parity.test.cjs@@ -0,0 +1,249 @@+'use strict';++const assert = require('node:assert/strict');+const fs = require('node:fs');+const path = require('node:path');+const test = require('node:test');+const vm = require('node:vm');++const loadTs = require('./load-ts.cjs');+const { BUNDLED_SKILL_IDS, validateHireManifest } = loadTs('src/shared/hire.ts');+const { MCP_CATALOG } = loadTs('src/shared/mcpCatalog.ts');++const ROOT = path.resolve(__dirname, '..');++function loadGalleryValidator() {+ const source = fs.readFileSync(path.join(ROOT, 'docs/hires/validator.js'), 'utf8');+ const context = { window: {} };+ vm.createContext(context);+ vm.runInContext(source, context, { filename: 'docs/hires/validator.js' });+ return context.window.HireSpec.validate;+}++const validateInGallery = loadGalleryValidator();++function manifest(overrides = {}) {+ return {+ spec: 'munder-difflin/hire@1',+ name: 'Parity check',+ ...overrides+ };+}++const parityCases = [+ {+ name: 'accepts a minimal manifest',+ raw: manifest(),+ expected: true+ },+ {+ name: 'accepts the provider alias and safe flags in split and inline forms',+ raw: manifest({+ provider: 'agy',+ commandFlags: ['--model', 'claude-sonnet-4-6', '--max-turns=80', '--output-format=json', '--verbose']+ }),+ expected: true+ },+ {+ name: 'accepts Cursor plus allowlisted skills and MCP servers',+ raw: manifest({+ provider: 'cursor',+ skills: ['md-hive-sync', 'md-audit'],+ mcpServers: ['fetch', 'github-token']+ }),+ expected: true+ },+ {+ name: 'accepts surrounding whitespace that the runtime trims from an https homepage',+ raw: manifest({ homepage: ' https://example.com/hire ' }),+ expected: true+ },+ {+ name: 'rejects a permission-escalating flag',+ raw: manifest({ commandFlags: ['--permission-mode', 'bypassPermissions'] }),+ expected: false+ },+ {+ name: 'rejects an arbitrary provider-selection flag',+ raw: manifest({ commandFlags: ['--provider', 'attacker-controlled'] }),+ expected: false+ },+ {+ name: 'rejects the Codex config override short flag',+ raw: manifest({ commandFlags: ['-c', 'model_providers.evil.base_url=https://attacker.example'] }),+ expected: false+ },+ {+ name: 'rejects a second bare value after the safe flag value is consumed',+ raw: manifest({ commandFlags: ['--model', 'safe-model', 'unexpected'] }),+ expected: false+ },+ {+ name: 'rejects an unknown skill id',+ raw: manifest({ skills: ['read-secrets'] }),+ expected: false+ },+ {+ name: 'rejects more than eight skills',+ raw: manifest({ skills: Array(9).fill('md-audit') }),+ expected: false+ },+ {+ name: 'rejects a non-string skill id',+ raw: manifest({ skills: ['md-audit', 42] }),+ expected: false+ },+ {+ name: 'rejects an unknown MCP catalog id',+ raw: manifest({ mcpServers: ['attacker-server'] }),+ expected: false+ },+ {+ name: 'rejects more than eight MCP servers',+ raw: manifest({ mcpServers: Array(9).fill('fetch') }),+ expected: false+ },+ {+ name: 'rejects a non-string MCP catalog id',+ raw: manifest({ mcpServers: ['fetch', null] }),+ expected: false+ }+];++for (const { name, raw, expected } of parityCases) {+ test(`runtime and gallery validator ${name}`, () => {+ const runtime = validateHireManifest(raw);+ const gallery = validateInGallery(raw);++ assert.equal(runtime.ok, expected, `runtime errors: ${runtime.errors.join('; ')}`);+ assert.equal(+ gallery.ok,+ expected,+ `gallery result must match runtime; gallery errors: ${Array.from(gallery.errors).join('; ')}`+ );+ if (!expected) assert.ok(gallery.errors.length > 0, 'invalid input must explain why it was rejected');+ });+}++function findHireManifests(directory) {+ return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {+ const fullPath = path.join(directory, entry.name);+ if (entry.isDirectory()) return findHireManifests(fullPath);+ return entry.name.endsWith('.hire.json') ? [fullPath] : [];+ });+}++test('every published hire manifest passes both validators', () => {+ const files = findHireManifests(path.join(ROOT, 'docs/hires/manifests'));+ assert.ok(files.length > 0, 'expected published hire manifests');++ for (const file of files) {+ const raw = JSON.parse(fs.readFileSync(file, 'utf8'));+ const runtime = validateHireManifest(raw);+ const gallery = validateInGallery(raw);+ const relative = path.relative(ROOT, file);+ assert.equal(runtime.ok, true, `${relative}: runtime rejected: ${runtime.errors.join('; ')}`);+ assert.equal(gallery.ok, true, `${relative}: gallery rejected: ${Array.from(gallery.errors).join('; ')}`);+ }+});++test('every runtime provider and allowlisted capability id passes the gallery validator', () => {+ for (const provider of ['claude', 'antigravity', 'agy', 'codex', 'cursor']) {+ assert.equal(validateInGallery(manifest({ provider })).ok, true, `provider ${provider}`);+ }+ for (const skill of BUNDLED_SKILL_IDS) {+ assert.equal(validateInGallery(manifest({ skills: [skill] })).ok, true, `skill ${skill}`);+ }+ for (const { id } of MCP_CATALOG) {+ assert.equal(validateInGallery(manifest({ mcpServers: [id] })).ok, true, `MCP server ${id}`);+ }+});++test('runtime and gallery validators agree across every manifest field boundary', () => {+ const fieldCases = [+ {},+ { spec: undefined },+ { spec: 'munder-difflin/hire@2' },+ { name: undefined },+ { name: '' },+ { name: ' '.repeat(3) },+ { name: 'n'.repeat(40) },+ { name: 'n'.repeat(41) },+ { name: 42 },+ { description: null },+ { description: 'd'.repeat(200) },+ { description: 'd'.repeat(201) },+ { goal: 'g'.repeat(4000) },+ { goal: 'g'.repeat(4001) },+ { character: 'c'.repeat(25) },+ { accent: false },+ { model: 'Gemini 3.1 Pro (High)' },+ { model: 'model%PATH%' },+ { model: 'model&command' },+ { model: 'm'.repeat(81) },+ { provider: 'claude' },+ { provider: 'agy' },+ { provider: 'custom' },+ { provider: 42 },+ { commandFlags: [] },+ { commandFlags: Array(17).fill('--verbose') },+ { commandFlags: [42] },+ { commandFlags: ['value-first'] },+ { commandFlags: ['--model', 'safe', '--output-format=json'] },+ { commandFlags: ['--MODEL', 'safe'] },+ { commandFlags: ['--model', 'unsafe%value'] },+ { capabilities: null },+ { capabilities: Array(13).fill('tag') },+ { capabilities: ['valid', 42, ''] },+ { isolate: true },+ { isolate: 'true' },+ { tokenCap: 1 },+ { tokenCap: 1e10 },+ { tokenCap: 0 },+ { tokenCap: 1.5 },+ { tokenCap: 1e10 + 1 },+ { author: 'a'.repeat(81) },+ { homepage: null },+ { homepage: ' ' },+ { homepage: 'http://example.com' },+ { homepage: 'https://example.com' },+ { homepage: ' https://example.com/hire ' },+ { skills: null },+ { skills: [] },+ { skills: [' md-audit '] },+ { skills: ['unknown'] },+ { mcpServers: null },+ { mcpServers: [] },+ { mcpServers: [' fetch '] },+ { mcpServers: ['unknown'] }+ ];++ for (const overrides of fieldCases) {+ const raw = manifest(overrides);+ const runtime = validateHireManifest(raw);+ const gallery = validateInGallery(raw);+ assert.equal(+ gallery.ok,+ runtime.ok,+ `${JSON.stringify(overrides)}\nruntime: ${runtime.errors.join('; ')}\ngallery: ${Array.from(gallery.errors).join('; ')}`+ );+ }+});++test('the published JSON schema reflects runtime providers and allowlists', () => {+ const schema = JSON.parse(fs.readFileSync(path.join(ROOT, 'docs/hires/spec/hire.schema.json'), 'utf8'));+ assert.deepEqual(+ schema.properties.provider.enum,+ ['claude', 'antigravity', 'agy', 'codex', 'cursor']+ );+ assert.deepEqual(schema.properties.skills.items.enum, Array.from(BUNDLED_SKILL_IDS));+ assert.deepEqual(schema.properties.mcpServers.items.enum, MCP_CATALOG.map(({ id }) => id));++ const commandTokenPattern = new RegExp(schema.properties.commandFlags.items.pattern);+ for (const token of ['--model', '--model=claude-sonnet-4-6', '--max-turns', '80', '--output-format=json', '--verbose']) {+ assert.equal(commandTokenPattern.test(token), true, `schema should accept ${token}`);+ }+ for (const token of ['--provider', '--permission-mode=bypassPermissions', '%PATH%']) {+ assert.equal(commandTokenPattern.test(token), false, `schema should reject ${token}`);+ }+});