Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { createHash } from 'node:crypto';
import { execFile } from 'node:child_process';
import { access, mkdir, readFile } from 'node:fs/promises';
import path from 'node:path';
import { promisify } from 'node:util';
import { assertSafeExecutionProfile, CINDY_UPSTREAM_COMMIT, compatibilityReport } from './compatibility.js';
const execFileAsync = promisify(execFile);
export interface HeadlessProfile {
id: string;
version: 1;
parentProfile?: string;
changedDimensions?: string[];
agentBackend: 'claude-code' | 'codex' | 'pi';
agentBinaryPath: string;
agentBinaryVersion: string;
supportedModelIds: string[];
model: {
provider: string;
requestedId: string;
routeId?: string;
contextLimit?: number;
thinkingBudget?: number | string;
effort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra';
maxOutputTokens?: number;
};
endpoint?: string;
permissionMode: 'bypassPermissions' | 'acceptEdits' | 'default' | 'ask' | 'auto' | 'plan';
systemPromptFile?: string;
expectedSystemPromptDigest?: string;
makerMemory: boolean;
nativeMemory: boolean;
projectContext: boolean;
containerSandbox?: boolean;
unsafeAllowUnsandboxedBypass?: boolean;
compaction?: { enabled: boolean; thresholdPct?: number };
throughputCap?: { outputTokensPerSecond: number; enforcement: 'external-proxy' };
inputPolicy?: { attachments: boolean; workspaceOnly: true; maxFiles?: number; maxFileBytes?: number };
mcpServers?: Array<{
id: string;
transport: 'http';
url: string;
bearerTokenEnvVar?: string;
headerEnvVars?: Record<string, string>;
startupTimeoutMs?: number;
requestTimeoutMs?: number;
}>;
nativeProviders?: Array<{
id: string;
name: string;
baseUrl: string;
api: 'anthropic-messages' | 'openai-responses' | 'openai-completions' | 'google-generative-ai';
apiKeyEnvVar?: string;
models: Array<{
id: string;
wireId?: string;
name?: string;
reasoning?: boolean;
contextWindow: number;
maxTokens: number;
input?: Array<'text' | 'image'>;
cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
}>;
}>;
piProjectSkills?: { enabled: boolean; roots: string[] };
}
export interface ResolvedProfile {
profile: HeadlessProfile;
profilePath: string;
systemPrompt?: string;
profileDigest: string;
systemPromptDigest: string | null;
}
export interface ProfileCapabilities {
schemaVersion: 1;
contractVersion: number;
profileId: string;
agentBackend: 'claude-code' | 'codex' | 'pi';
supportedModelIds: string[];
supportedPermissionModes: string[];
projectContext: boolean;
makerMemory: boolean;
nativeMemory: boolean;
nativeToolSurface: 'claude-code-default' | 'codex-app-server-default' | 'pi-rpc-default';
cindyMcpProviders: string[];
desktopOnlyProviders: string[];
multiTurnSession: true;
artifactContract: string[];
attachments: boolean;
customMcpServers: string[];
byomProviders: string[];
piProjectSkills: boolean;
}
function nonEmptyString(value: unknown, field: string): asserts value is string {
if (typeof value !== 'string' || value.trim() === '') throw new Error(`${field} must be a non-empty string`);
}
export function validateProfile(profile: unknown): HeadlessProfile {
if (!profile || typeof profile !== 'object' || Array.isArray(profile)) throw new Error('profile must be an object');
const value = profile as Partial<HeadlessProfile>;
nonEmptyString(value.id, 'profile.id');
nonEmptyString(value.agentBinaryPath, 'agentBinaryPath');
nonEmptyString(value.agentBinaryVersion, 'agentBinaryVersion');
if (value.version !== 1) throw new Error('profile.version must be 1');
if (!['claude-code', 'codex', 'pi'].includes(value.agentBackend ?? '')) throw new Error('agentBackend must be claude-code, codex or pi');
if (!Array.isArray(value.supportedModelIds) || value.supportedModelIds.length === 0) throw new Error('supportedModelIds must be non-empty');
if (value.supportedModelIds.some((id) => typeof id !== 'string' || id.trim() === '' || id === '*' || id === 'latest')) throw new Error('supportedModelIds must contain exact non-empty model IDs');
if (new Set(value.supportedModelIds).size !== value.supportedModelIds.length) throw new Error('supportedModelIds must not contain duplicates');
if (!value.model || typeof value.model !== 'object') throw new Error('model is required');
nonEmptyString(value.model.provider, 'model.provider');
nonEmptyString(value.model.requestedId, 'model.requestedId');
if (!value.supportedModelIds.includes(value.model.requestedId)) throw new Error(`model ${value.model.requestedId} is not supported by this profile`);
if (value.model.effort !== undefined && !['minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'].includes(value.model.effort)) throw new Error('model.effort must be minimal, low, medium, high, xhigh, max or ultra');
if (value.model.maxOutputTokens !== undefined && (!Number.isInteger(value.model.maxOutputTokens) || value.model.maxOutputTokens <= 0)) throw new Error('model.maxOutputTokens must be a positive integer');
if (value.agentBackend === 'codex' && value.model.maxOutputTokens !== undefined) throw new Error('model.maxOutputTokens is not supported by the codex backend');
if (value.agentBackend === 'pi' && (!Number.isInteger(value.model.contextLimit) || (value.model.contextLimit ?? 0) <= 0)) throw new Error('pi profiles require a positive model.contextLimit');
if (value.agentBackend === 'pi' && value.model.effort === 'ultra') throw new Error('ultra effort is not supported by the pi backend');
if (!['bypassPermissions', 'acceptEdits', 'default', 'ask', 'auto', 'plan'].includes(value.permissionMode ?? '')) throw new Error('unsupported permissionMode');
if (value.agentBackend === 'claude-code' && value.permissionMode === 'auto') throw new Error('auto permissionMode is only supported by codex and pi');
if (value.agentBackend === 'codex' && (value.permissionMode === 'acceptEdits' || value.permissionMode === 'default')) throw new Error(`${value.permissionMode} permissionMode is not supported by codex`);
if (value.agentBackend === 'pi' && value.permissionMode !== 'bypassPermissions') throw new Error('headless pi requires bypassPermissions because no interactive approval channel is available');
if (typeof value.makerMemory !== 'boolean' || typeof value.nativeMemory !== 'boolean' || typeof value.projectContext !== 'boolean') throw new Error('makerMemory, nativeMemory and projectContext must be boolean');
if (value.agentBackend !== 'pi' && value.makerMemory && value.nativeMemory) throw new Error('makerMemory and nativeMemory are mutually exclusive for claude-code and codex');
if (value.containerSandbox !== undefined && typeof value.containerSandbox !== 'boolean') throw new Error('containerSandbox must be boolean');
if (value.unsafeAllowUnsandboxedBypass !== undefined && typeof value.unsafeAllowUnsandboxedBypass !== 'boolean') throw new Error('unsafeAllowUnsandboxedBypass must be boolean');
if (value.unsafeAllowUnsandboxedBypass && value.permissionMode !== 'bypassPermissions') throw new Error('unsafeAllowUnsandboxedBypass requires bypassPermissions');
if (value.parentProfile && (!value.changedDimensions || value.changedDimensions.length === 0)) throw new Error('derived profiles require changedDimensions');
if (!value.parentProfile && value.changedDimensions?.length) throw new Error('changedDimensions requires parentProfile');
if (value.compaction?.enabled && (!Number.isFinite(value.compaction.thresholdPct) || (value.compaction.thresholdPct ?? 0) < 50 || (value.compaction.thresholdPct ?? 0) > 95)) throw new Error('enabled compaction thresholdPct must be between 50 and 95');
if (value.throughputCap && (!Number.isFinite(value.throughputCap.outputTokensPerSecond) || value.throughputCap.outputTokensPerSecond <= 0 || value.throughputCap.enforcement !== 'external-proxy')) throw new Error('throughputCap requires a positive rate and external-proxy enforcement');
if (value.inputPolicy) {
if (typeof value.inputPolicy.attachments !== 'boolean' || value.inputPolicy.workspaceOnly !== true) throw new Error('inputPolicy requires attachments boolean and workspaceOnly=true');
if (value.inputPolicy.maxFiles !== undefined) positiveInteger(value.inputPolicy.maxFiles, 'inputPolicy.maxFiles');
if (value.inputPolicy.maxFileBytes !== undefined) positiveInteger(value.inputPolicy.maxFileBytes, 'inputPolicy.maxFileBytes');
}
if (value.mcpServers !== undefined) {
if (!Array.isArray(value.mcpServers)) throw new Error('mcpServers must be an array');
const ids = new Set<string>();
for (const [index, server] of value.mcpServers.entries()) {
if (!server || typeof server !== 'object') throw new Error(`mcpServers[${index}] must be an object`);
if (!PROFILE_ID_RE.test(server.id) || ['__proto__', 'constructor', 'prototype', 'cindy_memory'].includes(server.id)) throw new Error(`mcpServers[${index}].id is invalid or reserved`);
if (ids.has(server.id)) throw new Error(`duplicate MCP server id: ${server.id}`);
ids.add(server.id);
if (server.transport !== 'http') throw new Error('headless custom MCP supports streamable HTTP only');
validateEndpoint(server.url, `mcpServers[${index}].url`);
if (server.bearerTokenEnvVar && !ENV_NAME_RE.test(server.bearerTokenEnvVar)) throw new Error(`mcpServers[${index}].bearerTokenEnvVar is invalid`);
for (const [header, envName] of Object.entries(server.headerEnvVars ?? {})) {
if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(header) || !ENV_NAME_RE.test(envName)) throw new Error(`mcpServers[${index}].headerEnvVars is invalid`);
}
if (server.startupTimeoutMs !== undefined) positiveInteger(server.startupTimeoutMs, `mcpServers[${index}].startupTimeoutMs`);
if (server.requestTimeoutMs !== undefined) positiveInteger(server.requestTimeoutMs, `mcpServers[${index}].requestTimeoutMs`);
}
}
if (value.nativeProviders !== undefined) {
if (value.agentBackend !== 'pi') throw new Error('nativeProviders are supported only by the pi backend');
if (!Array.isArray(value.nativeProviders) || value.nativeProviders.length === 0) throw new Error('nativeProviders must be a non-empty array');
const ids = new Set<string>();
for (const [index, provider] of value.nativeProviders.entries()) {
nonEmptyString(provider.id, `nativeProviders[${index}].id`);
nonEmptyString(provider.name, `nativeProviders[${index}].name`);
if (!PROFILE_ID_RE.test(provider.id) || provider.id === 'cindy' || ids.has(provider.id)) throw new Error(`nativeProviders[${index}].id is invalid, reserved or duplicated`);
ids.add(provider.id);
validateEndpoint(provider.baseUrl, `nativeProviders[${index}].baseUrl`);
if (!['anthropic-messages', 'openai-responses', 'openai-completions', 'google-generative-ai'].includes(provider.api)) throw new Error(`nativeProviders[${index}].api is invalid`);
if (provider.apiKeyEnvVar && !ENV_NAME_RE.test(provider.apiKeyEnvVar)) throw new Error(`nativeProviders[${index}].apiKeyEnvVar is invalid`);
if (!Array.isArray(provider.models) || provider.models.length === 0) throw new Error(`nativeProviders[${index}].models must be non-empty`);
for (const [modelIndex, model] of provider.models.entries()) {
nonEmptyString(model.id, `nativeProviders[${index}].models[${modelIndex}].id`);
positiveInteger(model.contextWindow, `nativeProviders[${index}].models[${modelIndex}].contextWindow`);
positiveInteger(model.maxTokens, `nativeProviders[${index}].models[${modelIndex}].maxTokens`);
}
}
if (!value.nativeProviders.some((provider) => provider.id === value.model?.provider && provider.models.some((model) => model.id === value.model?.requestedId))) throw new Error('selected Pi BYOM model must exist in nativeProviders');
}
if (value.piProjectSkills !== undefined) {
if (value.agentBackend !== 'pi') throw new Error('piProjectSkills are supported only by the pi backend');
if (typeof value.piProjectSkills.enabled !== 'boolean' || !Array.isArray(value.piProjectSkills.roots)) throw new Error('piProjectSkills requires enabled and roots');
if (value.piProjectSkills.enabled && value.piProjectSkills.roots.length === 0) throw new Error('enabled piProjectSkills requires at least one root');
for (const root of value.piProjectSkills.roots) {
nonEmptyString(root, 'piProjectSkills.roots[]');
if (path.isAbsolute(root) || root.split(/[\\/]/).includes('..')) throw new Error('piProjectSkills roots must be workspace-relative without parent traversal');
}
}
if (value.expectedSystemPromptDigest && !/^[a-f0-9]{64}$/.test(value.expectedSystemPromptDigest)) throw new Error('expectedSystemPromptDigest must be a lowercase sha256 digest');
return value as HeadlessProfile;
}
export function sha256(value: string | Buffer): string {
return createHash('sha256').update(value).digest('hex');
}
function canonicalize(value: unknown): unknown {
if (Array.isArray(value)) return value.map(canonicalize);
if (!value || typeof value !== 'object') return value;
return Object.fromEntries(Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => [key, canonicalize(child)]));
}
export function profileDigest(profile: HeadlessProfile): string {
return sha256(JSON.stringify(canonicalize(profile)));
}
function resolveProfileResource(value: string, profileDir: string, bundleRoot?: string): string {
if (!value.startsWith('bundle:')) return path.isAbsolute(value) ? value : path.resolve(profileDir, value);
if (!bundleRoot) throw new Error('bundle: profile resources require an explicit bundle root');
const logicalPath = value.slice('bundle:'.length);
if (!logicalPath || logicalPath.startsWith('/') || logicalPath.startsWith('\\') || /^[A-Za-z]:/.test(logicalPath)) {
throw new Error('bundle: resource must use a relative bundle path');
}
const segments = logicalPath.split(/[\\/]/);
if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
throw new Error('bundle: resource path contains an invalid segment');
}
const root = path.resolve(bundleRoot);
const resolved = path.resolve(root, ...segments);
if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) throw new Error('bundle: resource escapes the bundle root');
return resolved;
}
export async function readProfile(profilePath: string, bundleRoot?: string): Promise<ResolvedProfile> {
const absolutePath = path.resolve(profilePath);
const rawProfile = await readFile(absolutePath, 'utf8');
const profile = validateProfile(JSON.parse(rawProfile));
const canonicalProfileDigest = profileDigest(profile);
const lockPath = path.join(path.dirname(absolutePath), 'profile.lock.json');
const lock = await readFile(lockPath, 'utf8').then((raw) => JSON.parse(raw) as Record<string, unknown>, (error: NodeJS.ErrnoException) => {
if (error.code === 'ENOENT') return null;
throw error;
});
const activeLock = lock?.profileFile === path.basename(absolutePath) ? lock : null;
if (activeLock) {
if (activeLock.schemaVersion !== 1 || activeLock.status !== 'frozen' || activeLock.profileId !== profile.id) throw new Error('profile lock identity is invalid');
if (activeLock.profileFileSha256 !== sha256(rawProfile)) throw new Error('profile file does not match profile.lock.json');
if (activeLock.profileDigest !== canonicalProfileDigest) throw new Error('profile digest does not match profile.lock.json');
if (activeLock.agentBinaryVersion !== profile.agentBinaryVersion) throw new Error('profile Agent version does not match profile.lock.json');
if (activeLock.cindyUpstreamCommit !== CINDY_UPSTREAM_COMMIT) throw new Error('profile lock Cindy upstream commit is stale');
}
// Profiles may travel with a release or checkout. Resolve relative binaries
// beside the profile instead of depending on the caller's current directory.
profile.agentBinaryPath = resolveProfileResource(profile.agentBinaryPath, path.dirname(absolutePath), bundleRoot);
const endpointOverride = profile.agentBackend === 'claude-code' || profile.agentBackend === 'pi'
? process.env.CINDY_HEADLESS_BASE_URL ?? process.env.ANTHROPIC_BASE_URL
: undefined;
if (!profile.endpoint && endpointOverride) profile.endpoint = endpointOverride;
let systemPrompt: string | undefined;
let systemPromptDigest: string | null = null;
if (profile.systemPromptFile) {
const promptPath = resolveProfileResource(profile.systemPromptFile, path.dirname(absolutePath), bundleRoot);
systemPrompt = await readFile(promptPath, 'utf8');
systemPromptDigest = sha256(systemPrompt);
if (profile.expectedSystemPromptDigest && profile.expectedSystemPromptDigest !== systemPromptDigest) throw new Error('system prompt digest does not match expectedSystemPromptDigest');
} else if (profile.expectedSystemPromptDigest) {
throw new Error('expectedSystemPromptDigest requires systemPromptFile');
}
if (activeLock && activeLock.systemPromptDigest !== systemPromptDigest) throw new Error('system prompt does not match profile.lock.json');
return { profile, profilePath: absolutePath, systemPrompt, profileDigest: canonicalProfileDigest, systemPromptDigest };
}
export async function doctor(resolved: ResolvedProfile, outputDir?: string): Promise<{ ok: true; checks: Record<string, string | boolean> }> {
assertSafeExecutionProfile(resolved.profile);
await access(resolved.profile.agentBinaryPath);
const codexHome = process.env.CINDY_HEADLESS_CODEX_HOME ?? process.env.CODEX_HOME;
const nativeProviderAuth = resolved.profile.nativeProviders?.every((provider) => !provider.apiKeyEnvVar || Boolean(process.env[provider.apiKeyEnvVar]));
if ((resolved.profile.agentBackend === 'claude-code' || resolved.profile.agentBackend === 'pi') && !(process.env.CINDY_HEADLESS_API_KEY ?? process.env.ANTHROPIC_API_KEY) && !nativeProviderAuth) {
throw new Error('CINDY_HEADLESS_API_KEY or ANTHROPIC_API_KEY is required');
}
for (const server of resolved.profile.mcpServers ?? []) {
for (const envName of [server.bearerTokenEnvVar, ...Object.values(server.headerEnvVars ?? {})]) {
if (envName && !process.env[envName]) throw new Error(`custom MCP ${server.id} requires environment variable ${envName}`);
}
}
if (resolved.profile.agentBackend === 'codex' && !codexHome && !process.env.CINDY_CODEX_API_KEY) {
throw new Error('CINDY_HEADLESS_CODEX_HOME, CODEX_HOME, or gateway API key is required for codex');
}
if (codexHome) await access(path.resolve(codexHome));
const env = resolved.profile.agentBackend === 'codex' && codexHome
? { ...process.env, CODEX_HOME: path.resolve(codexHome) }
: process.env;
const versionResult = await execFileAsync(resolved.profile.agentBinaryPath, ['--version'], { timeout: 30_000, env });
const observedVersion = `${versionResult.stdout} ${versionResult.stderr}`.trim();
if (!observedVersion.includes(resolved.profile.agentBinaryVersion)) throw new Error(`agent binary version mismatch: expected ${resolved.profile.agentBinaryVersion}, observed ${observedVersion}`);
if (resolved.profile.agentBackend === 'codex') {
if (!process.env.CINDY_CODEX_API_KEY) {
const login = await execFileAsync(resolved.profile.agentBinaryPath, ['login', 'status'], { timeout: 30_000, env });
if (!`${login.stdout} ${login.stderr}`.toLowerCase().includes('logged in')) throw new Error('codex login status did not report an authenticated account');
}
}
if (outputDir) {
await mkdir(path.resolve(outputDir), { recursive: true });
await access(path.resolve(outputDir));
}
const compatibility = compatibilityReport(resolved.profile);
const endpointConfigured = resolved.profile.agentBackend === 'claude-code' || resolved.profile.agentBackend === 'pi'
? Boolean(resolved.profile.endpoint)
: Boolean(process.env.CINDY_CODEX_BASE_URL ?? process.env.CINDY_HEADLESS_BASE_URL);
return { ok: true, checks: { profile: true, contractVersion: String(compatibility.contractVersion), transport: compatibility.transport, securityIsolation: compatibility.security.safeForUntrustedWorkloads, agentBinary: resolved.profile.agentBinaryPath, agentBinaryVersion: observedVersion, authEnvironment: true, endpointConfigured, outputDirectory: outputDir ? path.resolve(outputDir) : 'not-requested', systemPromptDigest: resolved.systemPromptDigest ?? 'none' } };
}
export function capabilities(profile: HeadlessProfile): ProfileCapabilities {
const codex = profile.agentBackend === 'codex';
const pi = profile.agentBackend === 'pi';
return { schemaVersion: 1, contractVersion: compatibilityReport(profile).contractVersion, profileId: profile.id, agentBackend: profile.agentBackend, supportedModelIds: [...profile.supportedModelIds], supportedPermissionModes: pi ? ['bypassPermissions'] : codex ? ['bypassPermissions', 'ask', 'auto', 'plan'] : ['bypassPermissions', 'acceptEdits', 'default', 'ask', 'plan'], projectContext: profile.projectContext, makerMemory: profile.makerMemory, nativeMemory: profile.nativeMemory, nativeToolSurface: pi ? 'pi-rpc-default' : codex ? 'codex-app-server-default' : 'claude-code-default', cindyMcpProviders: profile.makerMemory ? ['cindy_memory'] : [], desktopOnlyProviders: [], multiTurnSession: true, artifactContract: ['identity.json', 'config.json', 'trace.raw.jsonl', 'trace.jsonl', 'stderr.log', 'usage.json', 'result.json'], attachments: profile.inputPolicy?.attachments ?? false, customMcpServers: profile.mcpServers?.map((server) => server.id) ?? [], byomProviders: profile.nativeProviders?.map((provider) => provider.id) ?? [], piProjectSkills: profile.piProjectSkills?.enabled ?? false };
}
const ENV_NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
const PROFILE_ID_RE = /^[a-z0-9][a-z0-9_-]{0,39}$/;
function positiveInteger(value: unknown, field: string): asserts value is number {
if (!Number.isInteger(value) || Number(value) <= 0) throw new Error(`${field} must be a positive integer`);
}
function validateEndpoint(raw: unknown, field: string): void {
nonEmptyString(raw, field);
const url = new URL(raw);
const loopback = url.hostname === '127.0.0.1' || url.hostname === '[::1]' || url.hostname === 'localhost';
if (url.username || url.password || (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))) {
throw new Error(`${field} must be HTTPS or loopback HTTP and must not contain credentials`);
}
}