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
/**
* Shareable "hires" — portable agent role templates (manifest spec v1).
*
* A hire manifest is a small JSON document that describes a role-configured
* agent (name, provider, model, flags, goal, budget) so it can be shared as a
* file or hosted in a community gallery and imported with one click via the
* `munderdifflin://hire?src=<https-url>` deep link or an in-app file picker.
*
* SECURITY MODEL — a manifest is untrusted input:
* - It can NEVER auto-spawn an agent. Importing only pre-fills the Add-Agent
* modal; the human reviews the final command and clicks spawn.
* - It cannot carry a raw executable/command. The spawn binary always comes
* from the locally configured provider preset; a manifest may only append
* flag-shaped arguments (validated below), which the modal shows in full.
* - All fields are length/shape-capped here, in one dependency-free module
* shared by main (deep link / file import) and renderer (prefill).
* - `skills` and `mcpServers` are references into the BUNDLED allowlists only —
* never raw specs. This is the same threat model as `commandFlags`: a manifest
* can never inject an arbitrary executable path, env var, or MCP spec.
* Write/secret MCP servers are surfaced for human consent at import, never
* auto-enabled (consistent with "import only pre-fills; human clicks spawn").
*/
import { mcpCatalogEntry } from './mcpCatalog';
import { MAX_AGENT_TOKEN_CAP } from './tokenCaps';
export const HIRE_SPEC_V1 = 'munder-difflin/hire@1';
/** Skill ids bundled in app resources (the only values a hire manifest may request
* in the `skills` field). A manifest can never name an arbitrary skill path —
* only these curated, read-only, no-secret skill ids are allowlisted. */
export const BUNDLED_SKILL_IDS: ReadonlySet<string> = new Set([
'md-hive-sync',
'md-fetch-summarize',
'md-audit'
]);
/** Providers a manifest may request ('agy' is accepted as an alias for
* 'antigravity'). 'custom' is deliberately NOT allowed — it would let a
* manifest choose an arbitrary local binary. */
export type HireProvider = 'claude' | 'antigravity' | 'codex' | 'cursor';
export interface HireManifest {
/** Spec tag; exactly `munder-difflin/hire@1` for this version. */
spec: typeof HIRE_SPEC_V1;
/** Agent display name (also seeds the hive id). Required. */
name: string;
/** One-line role, e.g. "Documentation writer" — lands in identity.md + card. */
description?: string;
/** The standing goal/mission text pre-filled into the goal field. */
goal?: string;
/** Office cast sprite id (e.g. 'pam'); unknown values fall back to default. */
character?: string;
/** Accent color name (e.g. 'mint'); unknown values fall back to default. */
accent?: string;
/** Which CLI the role is designed for. Default: the user's default provider. */
provider?: HireProvider;
/** Model id/label for that provider (e.g. 'claude-sonnet-4-6'). */
model?: string;
/** Extra flag-shaped args appended to the locally-built spawn command. Each flag
* must be in the safe-flag allowlist (see SAFE_FLAG_NAMES) and shell-metachar-free;
* anything else rejects the manifest (the command stays editable post-import). */
commandFlags?: string[];
/** Capability tags for the hive registry (routing hints). */
capabilities?: string[];
/** Spawn in an isolated git worktree. */
isolate?: boolean;
/** Per-agent total-token ceiling, applied to agentTokenCaps after spawn. */
tokenCap?: number;
/** Attribution shown in the import preview. */
author?: string;
/** Manifest home (gallery page). https only. */
homepage?: string;
/** Bundled skill ids to activate in the agent's workspace. References into
* BUNDLED_SKILL_IDS only — never raw file paths or arbitrary skill names. */
skills?: string[];
/** Default MCP catalog ids to enable for this agent. References into the
* MCP_CATALOG allowlist only — never raw specs. Safe-readonly ids are
* pre-filled; write/secret ids are surfaced for human consent at import
* and never auto-enabled. */
mcpServers?: string[];
}
export interface HireValidation {
ok: boolean;
manifest?: HireManifest;
errors: string[];
/** MCP catalog ids present in the manifest's `mcpServers` that are NOT
* safe-readonly (write or secret tier). These must be surfaced to the human
* for explicit consent before they are enabled — they are NEVER auto-enabled. */
consentRequired?: string[];
}
const PROVIDERS: readonly string[] = ['claude', 'antigravity', 'codex', 'cursor'];
const MAX_BYTES = 64 * 1024;
/** A flag ("-x", "--flag", "--flag=value") or a bare value token that may follow
* a flag. Letters/digits plus a conservative punctuation set; no quotes,
* backticks, semicolons, pipes, ampersands, redirects, percent (cmd.exe
* %VAR% env-expansion), or whitespace. Args are passed to node-pty as argv
* (no shell), so this is defense in depth. */
const FLAG_RE = /^[A-Za-z0-9._\/=:,@+-]{1,100}$/;
/** Allowed characters in a model id/label. Model values flow into the spawn
* command line (`--model <value>`), so this MUST reject shell metacharacters —
* on Windows a `.cmd`/`.bat` provider shim routes the command through cmd.exe,
* where an unquoted `&`/`|`/`^`/`<`/`>`/`(`/`)` would chain a second command.
* Real model ids/labels only need letters, digits, spaces, and a little
* punctuation: `claude-sonnet-4-6[1m]`, `Gemini 3.1 Pro (High)`. No quotes,
* backticks, `$`, `;`, `&`, `|`, `^`, `<`, `>`, `%`, `!`. (The command field
* stays editable, so a legitimate exotic value can still be typed by hand.) */
const MODEL_RE = /^[A-Za-z0-9 ._()[\]\/:@+-]{1,80}$/;
/** Flags a manifest is ALLOWED to append — a default-deny ALLOWLIST.
*
* WHY AN ALLOWLIST: a manifest's `provider` is attacker-chosen and each CLI keeps
* adding flags, so a denylist of "dangerous" flags drifts and leaks (three rounds
* of re-review each found one more spelling that escaped — codex `-a`/`-s`, then
* `-c model_providers.*.base_url=…` backend-redirect credential exfil, then
* `--provider`). Default-deny closes the CLASS: only flags that PROVABLY cannot
* escalate permissions, redirect the backend / exfil credentials, read/write
* arbitrary files, inject prompt/config/MCP, or run commands may pass; every
* other flag-shaped token rejects the manifest outright.
*
* These names are the curated SAFE set, mined from the provider command
* references (claudeCommands.ts / codexCommands.ts) and presets
* (agentProvider.ts). The list is deliberately tiny — biased hard to EXCLUDE,
* because the spawn command stays editable after import, so a user who needs an
* exotic flag can add it by hand. Each is behavioral / output / a safety-cap
* only, with a single non-escalating value (or none):
* --model select the model id (claude/codex/agy modelFlag)
* --max-turns cap agentic turns (runaway guard, strictly safety-↑)
* --output-format headless output shape: text / json / stream-json
* --verbose logging verbosity only
* Matched case-insensitively against the flag NAME (part before any `=`), so both
* `--flag value` and `--flag=value` are covered. NOTHING permission / sandbox /
* approval / dir / config (incl. codex `-c`) / mcp / provider / base-url /
* system-prompt / settings related is ever allowlisted. */
const SAFE_FLAG_NAMES: ReadonlySet<string> = new Set([
'--model',
'--max-turns',
'--output-format',
'--verbose'
]);
/** True if a commandFlags token is an allowed flag. Handles `--x` and `--x=value`
* (matches the NAME before `=`, case-insensitive); short `-x` forms are not in
* the allowlist and so are rejected by default. */
function isSafeFlag(token: string): boolean {
if (!token.startsWith('-')) return false;
const name = token.split('=', 1)[0].toLowerCase();
return SAFE_FLAG_NAMES.has(name);
}
function str(v: unknown): v is string { return typeof v === 'string'; }
function capped(v: unknown, max: number, field: string, errors: string[], required = false): string | undefined {
if (v === undefined || v === null) {
if (required) errors.push(`"${field}" is required`);
return undefined;
}
if (!str(v)) { errors.push(`"${field}" must be a string`); return undefined; }
const t = v.trim();
if (required && !t) { errors.push(`"${field}" must not be empty`); return undefined; }
if (t.length > max) { errors.push(`"${field}" exceeds ${max} chars`); return undefined; }
return t || undefined;
}
/** Validate an untrusted parsed JSON value into a HireManifest. Pure; no I/O. */
export function validateHireManifest(raw: unknown): HireValidation {
const errors: string[] = [];
if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
return { ok: false, errors: ['manifest must be a JSON object'] };
}
const o = raw as Record<string, unknown>;
if (o.spec !== HIRE_SPEC_V1) {
return { ok: false, errors: [`unsupported spec "${String(o.spec)}" (expected "${HIRE_SPEC_V1}")`] };
}
const name = capped(o.name, 40, 'name', errors, true);
const description = capped(o.description, 200, 'description', errors);
const goal = capped(o.goal, 4000, 'goal', errors);
const character = capped(o.character, 24, 'character', errors)?.toLowerCase();
const accent = capped(o.accent, 24, 'accent', errors)?.toLowerCase();
const model = capped(o.model, 80, 'model', errors);
if (model !== undefined && !MODEL_RE.test(model)) {
errors.push('"model" contains disallowed characters (it goes onto the spawn command line; letters, digits, spaces and . _ - ( ) [ ] / : @ + only)');
}
const author = capped(o.author, 80, 'author', errors);
const homepage = capped(o.homepage, 300, 'homepage', errors);
let provider: HireProvider | undefined;
if (o.provider !== undefined) {
const p = str(o.provider) ? (o.provider === 'agy' ? 'antigravity' : o.provider) : o.provider;
if (str(p) && PROVIDERS.includes(p)) provider = p as HireProvider;
else errors.push(`"provider" must be one of ${PROVIDERS.join(', ')} (or "agy")`);
}
let commandFlags: string[] | undefined;
if (o.commandFlags !== undefined) {
if (!Array.isArray(o.commandFlags) || o.commandFlags.length > 16) {
errors.push('"commandFlags" must be an array of at most 16 items');
} else {
commandFlags = [];
// DEFAULT-DENY: every flag-shaped token must name an allowlisted safe flag;
// a bare token is allowed only as the value immediately following an allowed
// `--flag` (so a value can never smuggle in a second, unknown flag).
let valueAllowed = false; // previous token was an allowed `--flag` (no inline =)
for (let i = 0; i < o.commandFlags.length; i++) {
const f = o.commandFlags[i];
if (!str(f) || !FLAG_RE.test(f)) {
errors.push(`commandFlags entry ${JSON.stringify(f)} is not a safe flag token`);
valueAllowed = false;
continue;
}
// The FIRST entry must be flag-shaped (defense in depth; kept explicit).
if (i === 0 && !f.startsWith('-')) {
errors.push('"commandFlags" must start with a flag (e.g. "--model")');
valueAllowed = false;
continue;
}
if (f.startsWith('-')) {
if (!isSafeFlag(f)) {
errors.push(`commandFlags entry ${JSON.stringify(f)} is not in the shared-hire safe-flag list — for safety a shared hire may only embed known-harmless flags (${[...SAFE_FLAG_NAMES].join(', ')}). If you need this flag, add it by hand in the command field after importing.`);
valueAllowed = false;
continue;
}
commandFlags.push(f);
valueAllowed = !f.includes('='); // a `--flag value` form may take one value next
} 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")`);
continue;
}
commandFlags.push(f);
valueAllowed = false; // consume the value; no chained second value
}
}
if (commandFlags.length === 0) commandFlags = undefined;
}
}
let capabilities: string[] | undefined;
if (o.capabilities !== undefined) {
if (!Array.isArray(o.capabilities) || o.capabilities.length > 12) {
errors.push('"capabilities" must be an array of at most 12 items');
} else {
capabilities = o.capabilities.filter(str).map(c => c.trim().slice(0, 40)).filter(Boolean);
if (capabilities.length === 0) capabilities = undefined;
}
}
let isolate: boolean | undefined;
if (o.isolate !== undefined) {
if (typeof o.isolate === 'boolean') isolate = o.isolate;
else errors.push('"isolate" must be a boolean');
}
let tokenCap: number | undefined;
if (o.tokenCap !== undefined) {
if (typeof o.tokenCap === 'number' && Number.isInteger(o.tokenCap) && o.tokenCap > 0 && o.tokenCap <= MAX_AGENT_TOKEN_CAP) tokenCap = o.tokenCap;
else errors.push('"tokenCap" must be a positive integer (max 1e10)');
}
// skills — allowlist: references into BUNDLED_SKILL_IDS only; max 8
let skills: string[] | undefined;
if (o.skills !== undefined) {
if (!Array.isArray(o.skills) || o.skills.length > 8) {
errors.push('"skills" must be an array of at most 8 items');
} else {
skills = [];
for (const s of o.skills) {
if (!str(s) || !s.trim()) { errors.push('"skills" entries must be non-empty strings'); continue; }
const id = s.trim();
if (!BUNDLED_SKILL_IDS.has(id)) {
errors.push(`"skills" entry ${JSON.stringify(id)} is not a bundled skill id — a hire may only reference the built-in safe skills (${[...BUNDLED_SKILL_IDS].join(', ')})`);
} else {
skills.push(id);
}
}
if (skills.length === 0) skills = undefined;
}
}
// mcpServers — allowlist: references into MCP_CATALOG only; max 8; write/secret surfaced for consent
let mcpServers: string[] | undefined;
const consentRequired: string[] = [];
if (o.mcpServers !== undefined) {
if (!Array.isArray(o.mcpServers) || o.mcpServers.length > 8) {
errors.push('"mcpServers" must be an array of at most 8 items');
} else {
mcpServers = [];
for (const s of o.mcpServers) {
if (!str(s) || !s.trim()) { errors.push('"mcpServers" entries must be non-empty strings'); continue; }
const id = s.trim();
const entry = mcpCatalogEntry(id);
if (!entry) {
errors.push(`"mcpServers" entry ${JSON.stringify(id)} is not a known catalog id — a hire may only reference built-in MCP servers`);
} else {
mcpServers.push(id);
if (entry.tier !== 'safe-readonly') consentRequired.push(id);
}
}
if (mcpServers.length === 0) mcpServers = undefined;
}
}
if (homepage && !homepage.startsWith('https://')) errors.push('"homepage" must be https');
if (errors.length > 0 || !name) return { ok: false, errors };
return {
ok: true,
errors: [],
consentRequired: consentRequired.length > 0 ? consentRequired : undefined,
manifest: { spec: HIRE_SPEC_V1, name, description, goal, character, accent, provider, model, commandFlags, capabilities, isolate, tokenCap, author, homepage, skills, mcpServers }
};
}
/** Parse a `munderdifflin://hire?src=<https-url>` deep link. Returns the https
* manifest URL, or null if the link is not a well-formed hire link. */
export function parseHireDeepLink(link: string): string | null {
let u: URL;
try { u = new URL(link); } catch { return null; }
if (u.protocol !== 'munderdifflin:') return null;
// Both munderdifflin://hire?src= (host) and munderdifflin:hire?src= (path).
const action = (u.host || u.pathname.replace(/^\/+/, '')).toLowerCase();
if (action !== 'hire') return null;
const src = u.searchParams.get('src');
if (!src) return null;
let s: URL;
try { s = new URL(src); } catch { return null; }
if (!isAllowedManifestUrl(s)) return null;
return s.toString();
}
/** https everywhere; plain http is allowed ONLY for loopback (local gallery
* development) — a remote page can never point the app at an http manifest. */
export function isAllowedManifestUrl(u: URL): boolean {
if (u.protocol === 'https:') return true;
if (u.protocol !== 'http:') return false;
return u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '[::1]';
}
/** Byte cap shared by the deep-link fetcher and the file importer. */
export const HIRE_MAX_BYTES = MAX_BYTES;