clilinkapi 0.1.0

package/dist/src/sandbox.js

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { writeFile, unlink, symlink, access } from 'node:fs/promises';
+import { CliLinkAPIError } from './errors.js';
+export function profileArgs(workspace, secrets) {
+    const fs = { ':root': 'deny', ':minimal': 'read', [workspace.path]: workspace.access === 'read-only' ? 'read' : 'write', [process.execPath]: 'read' };
+    for (const secret of secrets)
+        fs[secret] = 'deny';
+    for (const name of ['.git', '.codex', '.agents'])
+        fs[path.join(workspace.path, name)] = 'read';
+    const table = Object.entries(fs).map(([key, value]) => `${JSON.stringify(key)}=${JSON.stringify(value)}`).join(',');
+    // Explicitly skip project config layers while allowing their files to exist.
+    return ['-c', `projects={${JSON.stringify(workspace.path)}={trust_level="untrusted"}}`, '-c', 'default_permissions="clilinkapi"', '-c', `permissions.clilinkapi.filesystem={${table}}`, '-c', 'permissions.clilinkapi.network.enabled=false'];
+}
+export function requireNativePlatform(allowUnqualifiedWindowsExecution = false, platform = process.platform) {
+    // Opt-in permits attempts without claiming Windows isolation is qualified.
+    if (platform === 'win32') {
+        if (allowUnqualifiedWindowsExecution)
+            return;
+        throw new CliLinkAPIError(503, 'native_isolation_unavailable', 'Native Windows agent execution is disabled: restricted-token and read-boundary enforcement have not passed qualification. To attempt execution without qualification checks, explicitly set provider.allowUnqualifiedWindowsExecution=true.');
+    }
+    if (!['linux', 'darwin'].includes(platform))
+        throw new CliLinkAPIError(503, 'native_isolation_unavailable', 'No qualified native sandbox for this platform.');
+}
+export async function probeIsolation(rpc, workspace, home, signal, allowUnqualifiedWindowsExecution = false) {
+    requireNativePlatform(allowUnqualifiedWindowsExecution);
+    if (process.platform === 'win32' && allowUnqualifiedWindowsExecution)
+        return;
+    const nonce = randomUUID();
+    const local = path.join(workspace.path, `.clilinkapi-probe-${nonce}`);
+    const outside = path.join(home, `.clilinkapi-probe-${nonce}`);
+    const escaped = path.join(workspace.path, `.clilinkapi-link-${nonce}`);
+    const output = path.join(workspace.path, `.clilinkapi-write-${nonce}`);
+    // Fresh harmless sentinels only; never read real credentials in a probe.
+    const cleanup = [local, outside, escaped, output];
+    try {
+        await writeFile(local, nonce, { flag: 'wx', mode: 0o600 });
+        await writeFile(outside, nonce, { flag: 'wx', mode: 0o600 });
+        await symlink(outside, escaped);
+        const probe = `const f=require('node:fs');const c=require('node:child_process');const [local,outside,link,output,mode,nonce]=process.argv.slice(1);let ok=f.readFileSync(local,'utf8')===nonce;for(const p of [outside,link]){try{f.readFileSync(p);ok=false}catch(e){if(!['EACCES','EPERM','ENOENT'].includes(e.code))ok=false}try{f.appendFileSync(p,'x');ok=false}catch(e){if(!['EACCES','EPERM','ENOENT'].includes(e.code))ok=false}}let wrote=false;try{f.writeFileSync(output,'probe');wrote=true}catch(e){if(!['EACCES','EPERM','EROFS'].includes(e.code))ok=false}ok=ok&&(wrote===(mode==='read-write'));const child=c.spawnSync(process.execPath,['-e',"try{require('node:fs').readFileSync(process.argv[1]);process.exit(9)}catch(e){process.exit(['EACCES','EPERM','ENOENT'].includes(e.code)?0:8)}",outside]);ok=ok&&child.status===0;process.stdout.write(ok?'ISOLATION_OK':'ISOLATION_FAILED');process.exit(ok?0:7);`;
+        const result = await rpc.request('command/exec', { command: [process.execPath, '-e', probe, local, outside, escaped, output, workspace.access, nonce], cwd: workspace.path, permissionProfile: 'clilinkapi', timeoutMs: 15000, outputBytesCap: 4096 }, signal);
+        if (result.exitCode !== 0 || result.stdout !== 'ISOLATION_OK')
+            throw new Error('probe failed');
+        if (workspace.access === 'read-only') {
+            try {
+                await access(output);
+                throw new Error('read-only probe wrote');
+            }
+            catch (e) {
+                if (!(e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT'))
+                    throw e;
+            }
+        }
+    }
+    catch {
+        throw new CliLinkAPIError(503, 'native_isolation_unavailable', 'Native sandbox read, write, symlink or subprocess isolation probe failed. Install native sandbox prerequisites; no agent turn was started.');
+    }
+    finally {
+        for (const filename of cleanup)
+            await unlink(filename).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/src/server.js

@@ -0,0 +1,164 @@
+import http from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { once } from 'node:events';
+import os from 'node:os';
+import { authenticate } from './auth.js';
+import { CliLinkAPIError, errorBody, normalizeError } from './errors.js';
+import { parseRequest, selectModel, translate } from './requests.js';
+import { ExecutionSlots } from './sessions.js';
+import { Redactor } from './redaction.js';
+const json = (response, status, body) => { response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' }); response.end(JSON.stringify(body)); };
+async function sse(response, body, signal) {
+    signal.throwIfAborted();
+    if (!response.write(`data: ${typeof body === 'string' ? body : JSON.stringify(body)}\n\n`))
+        await once(response, 'drain', { signal });
+}
+export function createServer(config, provider, log = value => console.log(JSON.stringify(value))) {
+    const slots = new ExecutionSlots(config.server.maxConcurrency);
+    const discovery = new ExecutionSlots(config.server.maxConcurrency);
+    const controllers = new Set();
+    const server = http.createServer(async (request, response) => {
+        const id = 'chatcmpl-' + randomUUID();
+        const started = Date.now();
+        const controller = new AbortController();
+        controllers.add(controller);
+        const signal = controller.signal;
+        let release;
+        let streaming = false;
+        let timedOut = false;
+        response.setHeader('x-request-id', id);
+        const timer = setTimeout(() => { timedOut = true; controller.abort(); }, config.server.timeoutMs);
+        const disconnect = () => { if (!response.writableFinished)
+            controller.abort(); };
+        response.on('close', disconnect);
+        request.on('aborted', disconnect);
+        try {
+            authenticate(request.headers.authorization, config.auth.apiKey);
+            if (request.url === '/v1/models' && request.method === 'GET') {
+                release = discovery.acquire(id);
+                const models = await provider.models(signal);
+                json(response, 200, { object: 'list', data: models.map(m => ({ id: m.id, object: 'model', owned_by: 'codex', reasoning_efforts: m.efforts })) });
+                return;
+            }
+            if (request.url !== '/v1/chat/completions' || request.method !== 'POST')
+                throw new CliLinkAPIError(404, 'not_found', 'Endpoint not found.');
+            if (request.headers['x-session-id'] || request.headers['x-thread-id'])
+                throw new CliLinkAPIError(400, 'session_resume_unsupported', 'Each request starts an isolated session. Send conversation history in messages.');
+            const workspaceId = request.headers['x-workspace-id'] ?? config.compatibility.defaultWorkspace;
+            if (typeof workspaceId !== 'string' || !Object.hasOwn(config.workspaces, workspaceId))
+                throw new CliLinkAPIError(400, 'invalid_workspace', 'A configured X-Workspace-ID header is required.');
+            const workspace = config.workspaces[workspaceId];
+            if (!request.headers['content-type']?.startsWith('application/json'))
+                throw new CliLinkAPIError(415, 'content_type', 'Use application/json.');
+            release = slots.acquire(workspace.path);
+            const chunks = [];
+            let bytes = 0;
+            const abortRead = () => { request.destroy(); };
+            signal.addEventListener('abort', abortRead, { once: true });
+            try {
+                for await (const chunk of request) {
+                    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                    bytes += buffer.length;
+                    if (bytes > config.server.maxBodyBytes)
+                        throw new CliLinkAPIError(413, 'request_too_large', 'Request body exceeds configured limit.');
+                    chunks.push(buffer);
+                }
+            }
+            finally {
+                signal.removeEventListener('abort', abortRead);
+            }
+            let value;
+            try {
+                value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            }
+            catch {
+                throw new CliLinkAPIError(400, 'invalid_json', 'Request body must be valid JSON.');
+            }
+            const parsed = parseRequest(value);
+            const selected = selectModel(parsed, await provider.models(signal), config.provider);
+            if (parsed.stream && !provider.capabilities.streaming)
+                throw new CliLinkAPIError(400, 'stream_unsupported', 'Provider does not support streaming.');
+            const created = Math.floor(Date.now() / 1000);
+            const base = { id, created, model: selected.model };
+            const chunk = (delta, finish = null) => ({ ...base, object: 'chat.completion.chunk', choices: [{ index: 0, delta, finish_reason: finish }] });
+            const redactor = new Redactor([config.auth.apiKey, config.provider.codexHome, os.homedir(), ...Object.values(config.workspaces).map(w => w.path)]);
+            let complete = false;
+            let receivedDelta = false;
+            for await (const event of provider.generate({ ...selected, ...translate(parsed.messages), workspace, signal, request: parsed })) {
+                signal.throwIfAborted();
+                if (parsed.stream && !streaming) {
+                    response.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache, no-store', connection: 'keep-alive', 'x-accel-buffering': 'no' });
+                    streaming = true;
+                    await sse(response, chunk({ role: 'assistant' }), signal);
+                }
+                if (event.type === 'delta') {
+                    receivedDelta = true;
+                    if (parsed.stream) {
+                        const text = redactor.push(event.text);
+                        if (text)
+                            await sse(response, chunk({ content: text }), signal);
+                    }
+                }
+                else if (event.type === 'tool_calls') {
+                    complete = true;
+                    if (parsed.stream) {
+                        await sse(response, chunk({ tool_calls: event.calls.map((call, index) => ({ index, ...call })) }), signal);
+                        await sse(response, chunk({}, 'tool_calls'), signal);
+                        await sse(response, '[DONE]', signal);
+                        response.end();
+                    }
+                    else
+                        json(response, 200, { ...base, object: 'chat.completion', choices: [{ index: 0, message: { role: 'assistant', content: null, tool_calls: event.calls }, finish_reason: 'tool_calls' }] });
+                }
+                else {
+                    complete = true;
+                    if (parsed.stream) {
+                        if (!receivedDelta && event.text)
+                            throw new CliLinkAPIError(502, 'stream_unavailable', 'Codex supplied only buffered final output; real-time streaming was unavailable. Retry with stream=false.');
+                        const text = redactor.push('', true);
+                        if (text)
+                            await sse(response, chunk({ content: text }), signal);
+                        await sse(response, chunk({}, 'stop'), signal);
+                        if (parsed.stream_options?.include_usage && event.usage)
+                            await sse(response, { ...base, object: 'chat.completion.chunk', choices: [], usage: event.usage }, signal);
+                        await sse(response, '[DONE]', signal);
+                        response.end();
+                    }
+                    else
+                        json(response, 200, { ...base, object: 'chat.completion', choices: [{ index: 0, message: { role: 'assistant', content: redactor.clean(event.text) }, finish_reason: 'stop' }], ...(event.usage ? { usage: event.usage } : {}) });
+                }
+            }
+            if (!complete)
+                throw new CliLinkAPIError(502, 'missing_final_response', 'Codex ended without a final response.');
+        }
+        catch (error) {
+            const safe = timedOut ? new CliLinkAPIError(504, 'timeout', 'Request timed out; execution was cancelled. Changes may already have occurred.') : normalizeError(error);
+            if (!response.destroyed && !response.writableEnded) {
+                if (streaming) {
+                    await sse(response, errorBody(safe), AbortSignal.timeout(1000)).catch(() => undefined);
+                    response.end();
+                }
+                else {
+                    if (safe.status === 401)
+                        response.setHeader('www-authenticate', 'Bearer');
+                    json(response, safe.status, errorBody(safe));
+                }
+            }
+            log({ request_id: id, event: 'request_error', code: safe.code, status: safe.status });
+        }
+        finally {
+            clearTimeout(timer);
+            release?.();
+            controllers.delete(controller);
+            response.off('close', disconnect);
+            request.off('aborted', disconnect);
+            log({ request_id: id, event: 'request_finished', duration_ms: Date.now() - started, status: response.statusCode });
+        }
+    });
+    server.requestTimeout = config.server.timeoutMs;
+    server.headersTimeout = Math.min(config.server.timeoutMs, 10000);
+    server.maxHeadersCount = 50;
+    return { server, async close() { for (const c of controllers)
+            c.abort(); server.closeAllConnections(); await new Promise(resolve => server.close(() => resolve())); await provider.close(); } };
+}
+//# sourceMappingURL=server.js.map

package/dist/src/sessions.js

@@ -0,0 +1,19 @@
+import { CliLinkAPIError } from './errors.js';
+// Deliberately stateless API: each request creates a fresh, ephemeral Codex thread.
+// Clients submit history; raw thread IDs and resumption are never accepted.
+export class ExecutionSlots {
+    limit;
+    active = new Set();
+    constructor(limit) {
+        this.limit = limit;
+    }
+    acquire(workspace) {
+        if (this.active.has(workspace))
+            throw new CliLinkAPIError(409, 'workspace_busy', 'A request is already executing in this workspace.');
+        if (this.active.size >= this.limit)
+            throw new CliLinkAPIError(429, 'clilinkapi_busy', 'CliLinkAPI concurrency limit reached.');
+        this.active.add(workspace);
+        return () => { this.active.delete(workspace); };
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/src/startup.js

@@ -0,0 +1,46 @@
+import os from 'node:os';
+export function startupMessage(config, address) {
+    const host = address.address;
+    const urlHost = host === '0.0.0.0' ? '127.0.0.1' : host === '::' ? '::1' : host;
+    const baseUrl = `http://${urlHost.includes(':') ? `[${urlHost}]` : urlHost}:${address.port}`;
+    const row = (label, value) => `  ${label.padEnd(16)} ${value}`;
+    return [
+        '',
+        '  +----------------------------------------------------------+',
+        '  |  CliLinkAPI                                              |',
+        '  |  Codex-powered OpenAI-compatible API                      |',
+        '  +----------------------------------------------------------+',
+        '',
+        '  SERVER INFORMATION',
+        row('Status', 'LISTENING'),
+        row('Host ID', os.hostname()),
+        row('Host / IP', host),
+        row('Port', address.port),
+        row('Process ID', process.pid),
+        row('Base URL', baseUrl),
+        row('API base URL', `${baseUrl}/v1`),
+        ...(host === '0.0.0.0' || host === '::' ? [row('Bind scope', 'All interfaces (URLs above use loopback)')] : []),
+        '',
+        '  ENDPOINTS',
+        `  GET   ${baseUrl}/v1/models`,
+        '        List available models and reasoning efforts.',
+        `  POST  ${baseUrl}/v1/chat/completions`,
+        '        Create a chat completion; supports SSE streaming.',
+        ...(process.platform === 'win32' ? [config.provider.allowUnqualifiedWindowsExecution
+                ? '        WARNING: Unqualified Windows execution enabled; isolation probes skipped.'
+                : '        Agent execution is currently disabled on Windows.'] : []),
+        '',
+        '  REQUEST SETTINGS',
+        row('Authentication', 'Authorization: Bearer <API_KEY> (all endpoints)'),
+        row('POST content', 'Content-Type: application/json'),
+        row('Workspace', config.compatibility.defaultWorkspace
+            ? `${config.compatibility.defaultWorkspace} (default; override with X-Workspace-ID)`
+            : 'X-Workspace-ID header required for POST'),
+        row('Concurrency', config.server.maxConcurrency),
+        row('Timeout', `${config.server.timeoutMs / 1000}s`),
+        '',
+        '  Press Ctrl+C to stop the server.',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=startup.js.map

package/dist/src/tool-sessions.js

@@ -0,0 +1,54 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { CliLinkAPIError } from './errors.js';
+const hash = (v) => createHash('sha256').update(JSON.stringify(v, (key, value) => {
+    if (key === 'arguments' && typeof value === 'string') {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    return value && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) : value;
+})).digest('hex');
+const binding = (i) => hash([i.workspace, i.model, i.effort, i.request?.tools ?? [], i.request?.tool_choice ?? 'auto']);
+const history = (messages) => hash(JSON.parse(JSON.stringify(messages, (key, value) => key === 'content' && (value === null || value === '') ? undefined : value)));
+export class ToolSessions {
+    limit;
+    ttl;
+    close;
+    entries = new Map();
+    hasWorkspace(workspace) { return [...this.entries.values()].some(e => e.workspace === workspace); }
+    constructor(limit, ttl, close) {
+        this.limit = limit;
+        this.ttl = ttl;
+        this.close = close;
+    }
+    put(input, value, name, args) {
+        if (this.entries.size >= this.limit)
+            throw new CliLinkAPIError(429, 'pending_tool_limit', 'Too many pending tool continuations.');
+        const call = { id: 'call_' + randomUUID().replaceAll('-', ''), type: 'function', function: { name, arguments: JSON.stringify(args) } };
+        const timer = setTimeout(() => { this.entries.delete(call.id); void this.close(value).catch(() => undefined); }, this.ttl);
+        timer.unref();
+        this.entries.set(call.id, { value, workspace: input.workspace.path, binding: binding(input), history: history(input.request.messages), call: structuredClone(call), timer });
+        return call;
+    }
+    take(input) {
+        const messages = input.request?.messages;
+        const last = messages?.at(-1);
+        if (!messages || last?.role !== 'tool')
+            return;
+        const entry = this.entries.get(last.tool_call_id);
+        if (!entry)
+            throw new CliLinkAPIError(409, 'tool_session_expired', 'Tool continuation expired, was consumed, or belongs to another server. Restart the agent conversation; do not replay side effects automatically.');
+        const assistant = messages.at(-2);
+        if (entry.binding !== binding(input) || entry.history !== history(messages.slice(0, -2)) || assistant?.role !== 'assistant' || (assistant.content !== undefined && assistant.content !== null && assistant.content !== '') || hash(assistant.tool_calls) !== hash([entry.call]))
+            throw new CliLinkAPIError(409, 'tool_session_mismatch', 'Tool continuation must preserve workspace, model, reasoning, tool definitions and conversation history.');
+        clearTimeout(entry.timer);
+        this.entries.delete(last.tool_call_id);
+        return { value: entry.value, result: last.content };
+    }
+    async closeAll() { const entries = [...this.entries.values()]; this.entries.clear(); for (const e of entries)
+        clearTimeout(e.timer); await Promise.all(entries.map(e => this.close(e.value))); }
+}
+//# sourceMappingURL=tool-sessions.js.map

package/docs/architecture.md

@@ -0,0 +1,13 @@
+# Architecture and provider integration
+
+`server.ts` owns HTTP authentication order, bounded bodies, OpenAI-shaped errors, SSE/backpressure and disconnect/timeout signals. `config.ts` owns strict runtime validation and directory authorization. `sessions.ts` locks workspace execution within one clilinkapi process; new requests are isolated; tool-sessions.ts retains bounded, expiring one-use continuations for external tool results and reserves their workspace. `permissions.ts` owns secret-file permissions. `sandbox.ts` owns native profiles and preflight probes. `requests.ts` owns message and reasoning translation. Providers are registered in `providers/registry.ts` behind `providers/types.ts`.
+
+The only implemented provider is Codex. Its adapter owns login verification, catalog pagination/filtering, thread creation, native reasoning configuration, final-answer extraction, cancellation and normalized errors. RPC uses a dedicated stdio app-server per operation. No app-server TCP listener is exposed. Request IDs correlate safe structured logs; prompts, responses, headers, account identity and raw upstream stderr are never logged. Metadata and generation are bounded separately. Slow consumers are subject to the request deadline; RPC event count, line size and final delta accumulation are bounded. No automatic clilinkapi retries occur.
+
+The official SDK was inspected first. Version 0.155.0 exposes `Thread.run`, `runStreamed`, AbortSignal and sandbox modes. Its typed thread options do not provide permission-profile selection/model discovery, and its `agent_message` events omit final-versus-commentary phase metadata. Current app-server provides `model/list`, incremental `item/agentMessage/delta`, phase-labelled items, and experimental named permission profiles. Therefore this release uses the official app-server instead of the SDK for execution and metadata. The CLI is used for official login and sandbox diagnostics only. The SDK remains pinned for comparison/migration; there is no fake SDK backend.
+
+Protocol fields were checked against `codex app-server generate-ts --experimental` from the pinned installed binary. In particular, its legacy `SandboxPolicy` lacks the `ReadOnlyAccess` field shown in newer online documentation, so the implementation uses `permissions: "clilinkapi"` on threads and `permissionProfile: "clilinkapi"` on standalone probes. It verifies the returned active profile and never passes a legacy `sandbox` override that could supersede the profile. Permission-profile APIs are experimental; reject incompatible versions and re-run platform checks before upgrades.
+
+To add a future provider, implement `Provider.models`, `generate`, `close`, and capability flags. `generate` yields actual final-response deltas and one completed result, accepts AbortSignal, and supplies usage only when the backend reports it. Normalize errors without forwarding sensitive backend messages. Own authentication and provider sessions entirely inside the adapter. Add explicit config discrimination and registry selection, validate native reasoning against discovery, and add adapter/protocol and live tests. Do not assume Claude/Gemini authentication, role mapping, sandbox controls or reasoning levels match Codex. Neither provider is implemented in this release.
+
+Official references: [Codex SDK](https://learn.chatgpt.com/docs/codex-sdk), [app-server protocol](https://learn.chatgpt.com/docs/app-server), [authentication](https://learn.chatgpt.com/docs/auth), [permission profiles](https://learn.chatgpt.com/docs/permissions), [native sandbox prerequisites](https://learn.chatgpt.com/docs/sandboxing). Local generated schema is authoritative for the pinned executable when online documentation is newer.