clilinkapi 0.1.0

package/docs/configuration.md

@@ -0,0 +1,463 @@
+# CliLinkAPI configuration guide
+
+This guide describes the configuration accepted by the current application. Commands run from the CliLinkAPI repository unless stated otherwise.
+
+## Contents
+
+- [First-time setup](#first-time-setup)
+- [Complete configuration template](#complete-configuration-template)
+- [Settings reference](#settings-reference)
+- [Workspace selection and paths](#workspace-selection-and-paths)
+- [Project skills and symbolic links](#project-skills-and-symbolic-links)
+- [Windows execution mode](#windows-execution-mode)
+- [Local and network access](#local-and-network-access)
+- [Configure n8n](#configure-n8n)
+- [Verify the connection](#verify-the-connection)
+- [Maintenance commands](#maintenance-commands)
+- [Troubleshooting](#troubleshooting)
+
+## First-time setup
+
+CliLinkAPI uses two different credentials:
+
+| Credential | Purpose | How to configure it |
+| --- | --- | --- |
+| CliLinkAPI API key | Authenticates n8n and other HTTP clients to this gateway | Generated by `setup`; stored in `auth.apiKey` |
+| Codex ChatGPT sign-in | Authenticates the gateway's Codex runtime | Run `login` using the dedicated Codex home |
+
+An OpenAI API key is not a replacement for either step. A desktop Codex login is not automatically shared with the dedicated service home.
+
+### 1. Install dependencies
+
+Use Node.js 22 or newer, then run:
+
+```powershell
+npm ci
+npm run build
+```
+
+The repository pins the official Codex runtime to version `0.155.0`. A global Codex installation is not needed.
+
+To register the standalone `clilinkapi` command, run once from this repository after building:
+
+```powershell
+npm.cmd link
+```
+
+You can then run these commands from any directory:
+
+```powershell
+clilinkapi serve
+clilinkapi serve "C:/WORKSPACE/CliLinkAPI/workspaces/clilinkapi.json"
+clilinkapi doctor
+```
+
+Use `clilinkapi serve`, without npm's `--` separator. Running `clilinkapi` alone displays help. Omitting the configuration path uses the runtime user's `~/.clilinkapi/clilinkapi.json`; it does not search the current directory. All commands shown below as `npm run clilinkapi -- COMMAND` can also be run as `clilinkapi COMMAND`.
+
+This is a Node.js CLI, so Node.js must remain installed. `npm link` points to this checkout: keep its path, dependencies, and compiled `dist` files available, and rebuild with `npm run build` after source changes. If PowerShell blocks the generated script, use `clilinkapi.cmd`. If the command is not found, ensure the directory reported by `npm prefix -g` is on your Windows `PATH`, then reopen the terminal. On Linux/macOS, use `npm link`; the command is installed under the global prefix's `bin` directory.
+
+### 2. Prepare workspace folders and a template
+
+Create the folders that the agent may use. For example, on Windows:
+
+```powershell
+New-Item -ItemType Directory -Force -Path C:/Projects/project-a
+New-Item -ItemType Directory -Force -Path C:/Documents/reference
+Copy-Item ./clilinkapi.example.json ./clilinkapi.setup.json
+notepad ./clilinkapi.setup.json
+```
+
+Edit the template's username and paths. Keep only workspaces you need. The template contains a placeholder key; `setup` replaces it with a securely generated key. Do not put a real key into this repository template.
+
+### 3. Create the private configuration
+
+```powershell
+npm run clilinkapi -- setup "~/.clilinkapi/clilinkapi.json" ./clilinkapi.setup.json
+```
+
+Setup creates private configuration and Codex-home directories, generates a key, and checks workspace boundaries. It never overwrites an existing configuration. If you already have a configuration, edit it instead of running setup again.
+
+The default configuration location is the runtime user's home directory plus `.clilinkapi/clilinkapi.json`, for example:
+
+```text
+C:/Users/geron/.clilinkapi/clilinkapi.json
+```
+
+Run setup, login, and serve under the same OS account. Configuration permissions are checked at startup.
+
+### 4. Sign in and check the runtime
+
+```powershell
+npm run clilinkapi -- login "~/.clilinkapi/clilinkapi.json"
+npm run clilinkapi -- doctor "~/.clilinkapi/clilinkapi.json"
+```
+
+Follow the official ChatGPT sign-in flow. If browser login is unavailable and your account supports device authentication:
+
+```powershell
+npm run clilinkapi -- login "~/.clilinkapi/clilinkapi.json" --device-auth
+```
+
+`doctor` checks platform eligibility and authenticated model discovery. It does not establish that a real generation or every sandbox operation will succeed.
+
+### 5. Start the server
+
+```powershell
+npm run clilinkapi -- serve "~/.clilinkapi/clilinkapi.json"
+```
+
+The banner shows the actual listening address, port, hostname, process ID, URLs, endpoints, and request settings. `LISTENING` means the HTTP server started; it is not a successful generation test. Stop with Ctrl+C.
+
+For compiled execution after `npm run build`:
+
+```powershell
+npm start -- "~/.clilinkapi/clilinkapi.json"
+```
+
+These CLI commands also work in a native Linux/macOS shell. Use native absolute JSON paths, such as `/home/service/.clilinkapi/codex` or `/Users/service/.clilinkapi/codex`, and existing workspace folders on that host. Linux/macOS generation still requires passing native isolation probes; see the [platform prerequisites](../README.md#install-natively).
+
+## Complete configuration template
+
+This is a setup template, not a ready-to-serve credential file. Replace `YOUR_USER` and workspace paths before running `setup`. When editing an existing private file, preserve its actual `auth.apiKey` instead of replacing it with this placeholder.
+
+```json
+{
+  "server": {
+    "host": "127.0.0.1",
+    "port": 3000,
+    "timeoutMs": 180000,
+    "maxConcurrency": 2,
+    "maxBodyBytes": 262144
+  },
+  "auth": {
+    "apiKey": "REPLACE_WITH_A_SECURE_RANDOM_KEY"
+  },
+  "compatibility": {
+    "defaultWorkspace": "project-a",
+    "toolTimeoutMs": 300000,
+    "maxPendingTools": 8
+  },
+  "provider": {
+    "type": "codex",
+    "authentication": "chatgpt",
+    "codexHome": "C:/Users/YOUR_USER/.clilinkapi/codex",
+    "allowedModels": [],
+    "allowUnqualifiedWindowsExecution": true,
+    "allowProjectSkills": true,
+    "allowSymbolicLinks": true
+  },
+  "workspaces": {
+    "project-a": {
+      "path": "C:/Projects/project-a",
+      "access": "read-write"
+    },
+    "reference-docs": {
+      "path": "C:/Documents/reference",
+      "access": "read-only"
+    }
+  }
+}
+```
+
+Use valid JSON: double-quoted keys and strings, no comments, no trailing commas. Windows paths can use forward slashes as above or escaped backslashes (`C:\\Projects\\project-a`). Unknown configuration fields are rejected. Defaults apply to omitted fields, not to `null`.
+
+## Settings reference
+
+### Server
+
+The entire `server` object may be omitted to use its defaults.
+
+| Setting | Default | Accepted values and behavior |
+| --- | --- | --- |
+| `server.host` | `127.0.0.1` | Nonempty bind address or resolvable hostname. Use `0.0.0.0` for all IPv4 interfaces. |
+| `server.port` | `3000` | Integer from 1 to 65535. Must be available. |
+| `server.timeoutMs` | `180000` | Integer from 1000 to 3600000; maximum request duration in milliseconds. Timeout cancels execution, but prior side effects are not rolled back. |
+| `server.maxConcurrency` | `2` | Integer from 1 to 16. Limits generation requests; model discovery has a separate pool of the same size. A workspace permits one active generation at a time. |
+| `server.maxBodyBytes` | `262144` | Integer from 1024 to 1048576. Maximum POST body size in bytes; default is 256 KiB. |
+
+### Authentication
+
+| Setting | Default | Accepted values and behavior |
+| --- | --- | --- |
+| `auth.apiKey` | Required | String of 43–256 characters, with at least 16 distinct characters. Common placeholder strings are rejected. Use `setup` or `rotate-key` to generate it. |
+
+All endpoints require `Authorization: Bearer <key>`. One shared key grants access to all configured workspaces; workspace IDs are not separate user permissions. Never paste real keys into support messages, source control, or screenshots.
+
+### Compatibility
+
+The entire `compatibility` object may be omitted.
+
+| Setting | Default | Accepted values and behavior |
+| --- | --- | --- |
+| `compatibility.defaultWorkspace` | Unset | Must exactly match a configured workspace ID. Used when a POST request has no `X-Workspace-ID` header. |
+| `compatibility.toolTimeoutMs` | `300000` | Integer from 1000 to 1800000. How long an external tool continuation can wait for the client to return its result. |
+| `compatibility.maxPendingTools` | `8` | Integer from 1 to 64. Maximum retained external tool continuations. |
+
+An explicit workspace header overrides the default. An invalid header is rejected even when the default is valid. Pending tool continuations are held in memory and are lost on restart; they reserve their workspace until consumed or expired.
+
+### Provider
+
+| Setting | Default | Accepted values and behavior |
+| --- | --- | --- |
+| `provider.type` | Required | Must be `"codex"`. |
+| `provider.authentication` | Required | Must be `"chatgpt"`. |
+| `provider.codexHome` | Required | Absolute native path to dedicated, private Codex storage. Setup can create it; normal startup requires it to exist. |
+| `provider.allowedModels` | `[]` | Exact model IDs to allow. An empty array exposes all visible models discovered from Codex. Nonempty IDs may contain letters, digits, `.`, `_`, and `-`. |
+| `provider.defaultModel` | Unset | Exact model ID used when the request omits `model`. It must be present in the available, filtered catalog when used. |
+| `provider.defaultReasoning` | Unset | Effort used when the request omits `reasoning_effort`. Must be supported by the chosen model. |
+| `provider.allowUnqualifiedWindowsExecution` | `true` | Boolean. On Windows, permits execution attempts without qualification probes. Explicit `false` blocks Windows generation. Does not bypass Linux/macOS probes. |
+| `provider.allowProjectSkills` | `true` | Boolean. Allows discovery and use of project skills. Set to `false` to explicitly disable skills found by the workspace scan. Project configuration remains ignored and bundled runtime skills remain disabled. |
+| `provider.allowSymbolicLinks` | `true` | Boolean. Allows existing symbolic links and Windows junctions whose resolved targets stay inside the same workspace. Set to `false` to reject them. External targets, broken links, directory cycles, and hard-linked files remain rejected. |
+
+Model selection order is request `model`, configured `defaultModel`, catalog default, then first available model. An explicitly requested/configured unavailable model fails instead of silently falling back.
+
+Effort selection order is request `reasoning_effort`, configured `defaultReasoning`, then the selected model's default. `Light`, `Medium`, and `Strong` map to `low`, `medium`, and `high`; these are valid only when the model supports the resulting value. Query `GET /v1/models` for actual IDs and `reasoning_efforts` before adding model defaults. Do not assume a fixed catalog.
+
+The dedicated home cannot contain custom `config.toml`, `AGENTS.md`, `AGENTS.override.md`, hooks, rules, plugins, or custom skills. The pinned runtime's generated `skills/.system` directories are permitted, but those bundled skills are disabled. Do not point this setting at your personalized desktop Codex home.
+
+## Workspace selection and paths
+
+`workspaces` must contain at least one entry. Each entry has:
+
+| Field | Requirement |
+| --- | --- |
+| Workspace ID | 1–64 letters, digits, underscores, or hyphens; case-sensitive. |
+| `path` | Existing absolute native directory path. |
+| `access` | Exactly `"read-only"` or `"read-write"`; defines requested native filesystem permissions. |
+
+For a text-generation-only n8n workflow, an existing empty `read-only` workspace can be used. A workspace is still required even when the prompt does not ask to read files.
+
+Folder rules:
+
+- Workspaces cannot be filesystem roots, overlap, or alias each other.
+- The configuration file and Codex home must be outside every workspace; workspaces cannot be inside the Codex home.
+- Workspace trees are inspected before new generation. Project folders and internal symbolic links follow the [project skills and symbolic links settings](#project-skills-and-symbolic-links).
+- Parent directories may contain `.codex`, `.agents`, `AGENTS.md`, or `AGENTS.override.md`; these entries do not block workspace validation.
+- Paths inside JSON are literal. `~`, `$HOME`, and `%USERPROFILE%` are not expanded there. Home shorthand is expanded only in the CLI configuration filename.
+
+Choose a workspace through a default:
+
+```json
+{
+  "compatibility": {
+    "defaultWorkspace": "project-a"
+  }
+}
+```
+
+The fragment above belongs in the full configuration; it is not a standalone config. Alternatively, send `X-Workspace-ID: project-a`. If an existing configuration uses `WORKSPACE`, use that exact ID rather than copying `project-a` from this guide.
+
+## Project skills and symbolic links
+
+Both settings default to `true`, including in existing configurations that omit them. They belong under `provider` and apply to all configured workspaces. Use JSON booleans (`true` or `false`), not quoted strings.
+
+To allow project skills and internal links, merge these fields into your existing `provider` object:
+
+```json
+{
+  "allowProjectSkills": true,
+  "allowSymbolicLinks": true
+}
+```
+
+To restrict both, use:
+
+```json
+{
+  "allowProjectSkills": false,
+  "allowSymbolicLinks": false
+}
+```
+
+These are provider fragments, not complete configuration files. Preserve the other provider fields and your existing API key. The settings are independent: for example, you can allow skills while rejecting symbolic links. Stop and restart the server after editing the private configuration. For compiled execution, run `npm run build` after updating application source, then restart with `npm start -- "~/.clilinkapi/clilinkapi.json"`.
+
+### Project skills
+
+Place project skills in `<workspace>/.agents/skills/<skill-name>/SKILL.md`. With `allowProjectSkills: true`, the runtime can discover and use them. With `false`, CliLinkAPI explicitly disables the skill files found in the workspace scan; their folders can remain in place.
+
+Allowing skills does not load project `.codex/config.toml`: the runtime still treats the workspace as untrusted for project configuration. Custom configuration and skills in the dedicated `provider.codexHome` remain rejected, and bundled runtime skills remain disabled. Parent-directory configuration and instructions no longer cause a workspace-validation error. This change removes the presence check; it does not guarantee that the runtime ignores ancestor instructions or skills.
+
+### Symbolic links and Windows junctions
+
+With `allowSymbolicLinks: true`, the workspace scan resolves existing links and checks the final target. Directory contents are inspected through link aliases as well.
+
+| Link in `C:/Projects/project-a` | Result |
+| --- | --- |
+| A file link to `C:/Projects/project-a/data/input.txt` | Allowed if the target exists. |
+| A directory link or junction to `C:/Projects/project-a/shared` | Allowed if it does not create a directory cycle. |
+| A chain of links ending inside `C:/Projects/project-a` | Allowed if all inspected links resolve within the workspace and no directory cycle is introduced. |
+| A link to `C:/Projects/project-b` or another external location | Rejected, even if that location is another configured workspace. |
+| A missing target, link loop, or directory link back to an ancestor | Rejected. |
+| A hard-linked file | Rejected regardless of this setting. |
+
+With `allowSymbolicLinks: false`, existing symbolic links and junctions in the workspace are rejected with `403 workspace_link`. The setting does not change operating-system privileges for creating links, configuration-file link restrictions, or the dedicated Codex home's rules. Native sandbox enforcement still governs operations during execution; see [security boundaries](security.md).
+
+## Windows execution mode
+
+Omitting `allowUnqualifiedWindowsExecution` is equivalent to setting it to `true`. This skips CliLinkAPI's Windows platform refusal and its per-generation qualification probes. The startup banner and `doctor` identify this mode.
+
+The native permission profile is still requested. Authentication, configuration ACL checks, workspace validation, runtime version checks, and dedicated-home validation also remain active. This setting does not repair `CreateRestrictedToken` failures or an unavailable elevated sandbox backend, and it does not switch to unrestricted execution.
+
+Read, ACL, descendant-process, and network confinement are not certified in this mode. To restore the Windows block, set this inside `provider` and restart:
+
+```json
+"allowUnqualifiedWindowsExecution": false
+```
+
+On Linux/macOS, native probes remain mandatory regardless of this setting. See [security boundaries](security.md) for the exact limits and trust assumptions.
+
+## Local and network access
+
+| Client location | Server bind | Client Base URL |
+| --- | --- | --- |
+| Same computer, native process | `127.0.0.1` | `http://127.0.0.1:3000/v1` |
+| Another LAN computer | `0.0.0.0` or the server's LAN IPv4 address | `http://SERVER_LAN_IP:3000/v1` |
+| Docker Desktop on the server computer | Interface reachable from Docker | `http://host.docker.internal:3000/v1` |
+| Remote network/cloud | Reachable deployment behind HTTPS | Your authenticated HTTPS gateway URL ending in `/v1` |
+
+For the LAN setup discussed in this project, an example is `http://192.168.0.96:3000/v1`. Substitute the server's current LAN address. A DHCP reservation can keep that address stable. `0.0.0.0` is a bind address, not the URL clients should use. Binding to it does not advertise a hostname or configure DNS.
+
+Change `server.host` to `0.0.0.0`, restart the gateway, and allow inbound TCP on the configured port through the server firewall. If an inbound Windows Firewall rule is needed, an administrator can use this private-network, local-subnet rule:
+
+```powershell
+New-NetFirewallRule -DisplayName "CliLinkAPI TCP 3000 (Private LAN)" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000 -Profile Private -RemoteAddress LocalSubnet
+```
+
+Run that only on the gateway host and adapt it to your network policy and chosen port. It does not apply to a network classified as Public. Do not disable the firewall to diagnose connectivity.
+
+From the client computer:
+
+```powershell
+Test-NetConnection dengero -Port 3000
+Test-NetConnection 192.168.0.96 -Port 3000
+```
+
+Ping alone does not test port 3000. If a hostname selects IPv6 and that connection fails while IPv4 succeeds, use the IPv4 URL. A listener bound to `0.0.0.0` listens on IPv4. Test from the actual n8n runtime environment; a container can have different connectivity from its host shell.
+
+Use plain HTTP only on a trusted network. The application does not terminate TLS itself; for remote access, use an HTTPS reverse proxy, restrict direct port access, and disable proxy buffering for SSE. Proxy/client timeouts should allow for the configured request duration.
+
+## Configure n8n
+
+In the OpenAI credential used by your **OpenAI Chat Model** node:
+
+| n8n field | Value |
+| --- | --- |
+| API Key | The gateway's `auth.apiKey`, with no `Bearer ` prefix in this field |
+| Organization ID | Empty |
+| Base URL | For example, `http://192.168.0.96:3000/v1` |
+| Custom header | Optional if a default workspace exists; otherwise `X-Workspace-ID` with an actual workspace ID |
+
+Enter the URL as plain text, not Markdown link syntax. Do not append `/chat/completions` to the credential Base URL. Remove stale custom workspace headers when switching to a default workspace.
+
+In the **OpenAI Chat Model** node attached to the AI Agent:
+
+1. Select the gateway credential and a model returned by its catalog.
+2. Turn **Use Responses API** off. The gateway implements Chat Completions, not `/v1/responses`.
+3. Set **Max Retries** to `0`; a retry could repeat an action already performed.
+4. Set **Timeout** to `180000` or match your gateway configuration.
+5. Leave temperature, Top P, maximum token settings, and penalties unset. Use text output; do not enable strict structured output or forced tool selection.
+6. Start with a simple user prompt before adding tools or a larger workflow.
+
+A green credential test confirms discovery connectivity/authentication, not successful generation. The AI Agent can still encounter workspace, request-validation, runtime, or sandbox failures afterward. See [n8n integration](n8n.md) for tool continuations and supported behavior.
+
+## Verify the connection
+
+The application currently exposes exactly these routes:
+
+| Method | Endpoint | Requirements |
+| --- | --- | --- |
+| GET | `/v1/models` | Bearer key; returns discovered models and supported reasoning efforts |
+| POST | `/v1/chat/completions` | Bearer key, JSON body, and a valid workspace header or configured default |
+
+There is no unauthenticated health route, root-page UI, Responses API, or embeddings endpoint. Use the exact route paths without query strings or trailing slashes.
+
+For a local test under the runtime account, this PowerShell example reads the key without printing it:
+
+```powershell
+$configFile = Join-Path $HOME '.clilinkapi/clilinkapi.json'
+$gatewayConfig = Get-Content -LiteralPath $configFile -Raw | ConvertFrom-Json
+$gatewayBase = 'http://127.0.0.1:3000/v1'
+$requestHeaders = @{ Authorization = 'Bearer ' + $gatewayConfig.auth.apiKey }
+$catalog = Invoke-RestMethod -Uri "$gatewayBase/models" -Headers $requestHeaders
+$catalog.data | Select-Object id, reasoning_efforts
+```
+
+Then send a minimal generation request. Select an existing workspace ID if you changed the template:
+
+```powershell
+if (-not $catalog.data.Count) { throw 'No available models; check allowedModels and login.' }
+$requestHeaders['X-Workspace-ID'] = 'project-a'
+$payload = @{
+  model = $catalog.data[0].id
+  stream = $false
+  messages = @(@{ role = 'user'; content = 'Reply with a short greeting. Do not read files or run commands.' })
+} | ConvertTo-Json -Depth 10
+$reply = Invoke-RestMethod -Method Post -Uri "$gatewayBase/chat/completions" -Headers $requestHeaders -ContentType 'application/json' -Body $payload -TimeoutSec 190
+$reply.choices[0].message.content
+```
+
+This second request performs a real model call and can consume account usage. Do not distribute the full private configuration to a remote n8n host; enter only the client API key into its credential store.
+
+## Maintenance commands
+
+| Command | Purpose |
+| --- | --- |
+| `setup CONFIG TEMPLATE` | Create a new private configuration and generated key; refuses overwrite |
+| `secure-config CONFIG` | Repair permissions without rotating the key or changing configuration content |
+| `login CONFIG [--device-auth]` | Sign the dedicated runtime into ChatGPT |
+| `doctor CONFIG` | Report platform mode and query the authenticated model catalog |
+| `serve CONFIG` | Start the gateway until stopped |
+| `rotate-key CONFIG` | Generate and atomically store a replacement gateway key |
+
+Prefix each with `npm run clilinkapi --`. Except for setup's template argument, the CLI can use its default configuration path when `CONFIG` is omitted.
+
+Configuration does not hot-reload. Stop the server, edit its private file, and restart. If using `npm start`, rebuild after source changes; `npm run clilinkapi -- serve` runs TypeScript source directly.
+
+To rotate a key:
+
+```powershell
+npm run clilinkapi -- rotate-key "~/.clilinkapi/clilinkapi.json"
+```
+
+Restart the server and update n8n's stored key. A running process continues using its old in-memory configuration until restarted.
+
+For permission repair:
+
+```powershell
+npm run clilinkapi -- secure-config "~/.clilinkapi/clilinkapi.json"
+```
+
+The configuration directory must be dedicated and contain only the config file and its configured `codex` child folder. This command refuses unrelated entries, symlinks, filesystem roots, and the user's home directory itself. A Codex home elsewhere must be secured separately. Preserve backups in a private location outside this dedicated directory and outside every workspace.
+
+## Troubleshooting
+
+| Symptom | Meaning and next step |
+| --- | --- |
+| `ECONNREFUSED` | No reachable listener at the selected address/port. Check that serve is running, its bind address, firewall, and the client runtime's network. Try the LAN IPv4 address if hostname IPv6 fails. |
+| `EADDRINUSE` on startup | Another process already uses the port. Stop the appropriate existing instance or select a different port and update clients. |
+| `401` | Missing or incorrect gateway Bearer key. Use `auth.apiKey`, not a ChatGPT token or OpenAI API key. Restart after key rotation. An unauthenticated test returning 401 does establish HTTP reachability. |
+| `404 Endpoint not found` | Check the exact Base URL and route. In n8n, turn off Use Responses API. |
+| `400 A configured X-Workspace-ID header is required` | Configure `compatibility.defaultWorkspace` or send a valid header. IDs are case-sensitive; an invalid explicit header overrides a valid default. |
+| `400 unsupported_request` | Remove unsupported sampling, token, strict-schema, or output-format options. Use text messages and Chat Completions. |
+| `400 unsupported_model` | Query `/v1/models`; use an available ID allowed by the filter. Review `defaultModel` too. |
+| `400 unsupported_reasoning_effort` | Use an effort listed for the selected model or omit the setting. |
+| `403 workspace_link` | Check `provider.allowSymbolicLinks`. When enabled, link targets must exist and resolve inside the same workspace without directory cycles. Hard-linked files remain blocked. Restart after changing the setting. |
+| Old `403 ancestor_configuration` message | The ancestor-directory restriction has been removed. Rebuild and restart the gateway to use the updated code. Configuration-directory permissions are a separate check and still apply. |
+| Old `403 workspace_config` message | Current code permits project `.codex` and `.agents` folders. Rebuild and restart the running gateway to pick up the update; these folders no longer cause this error merely by existing. |
+| Project skill unavailable | Check `provider.allowProjectSkills`, the project's `.agents/skills/<name>/SKILL.md` layout, and that the server was restarted. Custom skills in the dedicated Codex home are still rejected. |
+| `409 workspace_busy` | A request or external tool continuation holds the workspace. Wait for completion/expiry; avoid concurrent workflows against the same workspace. |
+| `409 tool_session_expired` | A tool continuation expired or was lost on restart. Check whether the external action ran before deliberately restarting the workflow. |
+| `413 request_too_large` | Reduce the request body or raise `maxBodyBytes` within its allowed range. |
+| `429` | Check the error code: local capacity and upstream usage limits require different remedies. Reduce concurrency or wait for account limits as appropriate. |
+| `503 native_isolation_unavailable` | On Windows, check for explicit `allowUnqualifiedWindowsExecution: false`. On Linux/macOS, inspect native sandbox prerequisites/probes. Turning the Windows flag on does not fix native backend failures. |
+| Restricted-token/elevated sandbox error | The runtime cannot initialize the requested Windows permissions. The unqualified-execution flag skips qualification only; it does not remove the native permission profile. |
+| `503 upstream_authentication` | Run `login` again as the service account using the same config and dedicated home. |
+| `502 upstream_error` or `upstream_closed` | Check the pinned runtime, service account, login, and sandbox availability with `doctor`. A green model test alone does not verify generation. |
+| `502 stream_unavailable` | Codex supplied buffered final output without real deltas. Retry deliberately with `stream: false` if appropriate. |
+| `504` | Review timeout, runtime availability, and workload. A cancelled request can already have performed actions; do not blindly retry. |
+| Dedicated Codex home rejection | Relocate the specific custom entry identified by the error, or configure a clean dedicated home and log in there. Keep credentials private. |
+| Invalid configuration / permissions error | Check JSON syntax, exact field names, value ranges, absolute paths, existing folders, and owner/private permissions. Use `secure-config` only for its supported dedicated layout. |
+
+For diagnosis, share the error code, status, relevant setting names, and sanitized terminal output. Do not share the full credential file. Normal request logs include request IDs, status, duration, and error codes rather than prompts or keys.
+
+Run one gateway process per set of workspace folders: locks and tool continuations are process-local. See [architecture](architecture.md) and [security boundaries](security.md) for operational limits.

package/docs/n8n.md

@@ -0,0 +1,43 @@
+# n8n AI Agent integration
+
+For initial setup, all configuration fields, network access, and troubleshooting, see the [configuration guide](configuration.md).
+
+CliLinkAPI implements the text Chat Completions and function-tool subset used by n8n's OpenAI Chat Model. It is not a complete implementation of every OpenAI API.
+
+**Runtime limitation:** Windows generation is attempted without isolation qualification by default. The adapter and HTTP tests do not establish a working live n8n/Codex run. Linux/macOS generation requires successful native isolation probes and ChatGPT login. `provider.allowUnqualifiedWindowsExecution` defaults to `true`; set it to `false` and restart to block Windows generation. This skips Windows qualification probes but still requests native permission profiles; runtime sandbox failures remain possible.
+
+## Gateway configuration
+
+Add this top-level object to your private `clilinkapi.json`, replacing `project-a` with an existing workspace ID, then restart the gateway:
+
+```json
+"compatibility": {
+  "defaultWorkspace": "project-a",
+  "toolTimeoutMs": 300000,
+  "maxPendingTools": 8
+}
+```
+
+The default allows n8n requests without a custom `X-Workspace-ID` header. An explicit header overrides it and must name a configured workspace. Every holder of the shared gateway key can access configured workspaces; this setting is not tenant isolation.
+
+## n8n settings
+
+1. Connect an **OpenAI Chat Model** node to your **AI Agent** node.
+2. Create an OpenAI credential using your **CliLinkAPI API key**, from `auth.apiKey`. Leave Organization ID empty. Set its Base URL to `http://127.0.0.1:3000/v1` when n8n runs directly on the same machine. Older node versions also expose Base URL under Options.
+3. Set **Use Responses API** to **off**. Select a model returned by the gateway's `/v1/models`, or enter its exact ID.
+4. Set **Max Retries** to `0` and **Timeout** to `180000` (or match the gateway timeout). Leave Sampling Temperature, Top P, Maximum Number of Tokens, and penalties unset. Use Text response format. Do not enable structured output or forced tool selection.
+5. Attach a simple n8n tool, such as Calculator, to the agent. Ask it to use that tool and report the result. Inspect the workflow execution to verify the tool actually ran.
+
+For Docker Desktop n8n, the host URL is `http://host.docker.internal:3000/v1`; the gateway must listen on an interface reachable from Docker and the firewall must allow it. The default loopback binding may not be reachable. For remote or cloud n8n, localhost refers to that remote server: use a reachable, authenticated HTTPS endpoint instead.
+
+These settings follow the [n8n OpenAI Chat Model documentation](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.lmchatopenai/) and its [node implementation](https://github.com/n8n-io/n8n/blob/master/packages/%40n8n/nodes-langchain/nodes/llms/LMChatOpenAi/LmChatOpenAi.node.ts). The upstream version can change; a live imported workflow has not been tested here.
+
+## Tool-call behavior
+
+The gateway registers client function definitions as Codex dynamic tools. A native `item/tool/call` becomes an OpenAI `tool_calls` response with `finish_reason: "tool_calls"`. n8n executes the tool. Its next request must contain the unchanged conversation, assistant tool call, and matching `role: "tool"` result. The gateway delivers the result to the same waiting Codex turn. Tool arguments are emitted as a complete JSON object, including in SSE; argument tokens are not simulated.
+
+Continuations are process-local, expire after five minutes by default, and are consumed once. The workspace is reserved while waiting. Restarting the gateway loses pending calls. On `409 tool_session_expired`, restart the conversation after checking whether the tool already performed side effects; do not replay automatically. Tool definitions, model, workspace, reasoning effort and earlier history must remain unchanged across a continuation. One tool is returned per response; concurrent tool execution is not promised.
+
+Supported: text messages, function tools, automatic/no tool choice, JSON and SSE responses, `n: 1`, and observed usage. Unsupported: Responses API, images/audio, embeddings, forced/required tools, strict schema guarantees, sampling controls and token caps. Unsupported behavior returns a clear error instead of silently ignoring it. Tools execute in n8n with n8n's own credentials and permissions.
+
+

package/docs/security.md

@@ -0,0 +1,32 @@
+# Security boundaries and release limitations
+
+**Windows coding-agent execution is attempted without qualification probes by default. Linux/macOS remain unqualified on this build host and require passing probes.** Set `provider.allowUnqualifiedWindowsExecution=false` to block Windows execution. Passing application tests is not evidence that an OS sandbox denies arbitrary reads.
+
+| Platform | Native mechanism | This release |
+| --- | --- | --- |
+| Windows | Codex restricted tokens/ACLs; strongest documented mode uses dedicated lower-privilege users and firewall rules | Initial probe failed `CreateRestrictedToken failed: 87`; the actual restricted-read profile reports `Restricted read-only access requires the elevated Windows sandbox backend`. No claim of read confinement, network confinement or process-tree isolation. Generation is attempted without qualification probes by default; login/catalog remain usable. |
+| Linux | Codex bubblewrap/seccomp; kernel/user namespace and system policy dependent | Eligible only after per-execution native probes pass; not executed on the Windows build host. No container/VM fallback and no unrestricted execution. |
+| macOS | Codex Seatbelt | Eligible only after per-execution native probes pass; not executed on the Windows build host. |
+
+The custom profile grants `:minimal` runtime reads, the selected workspace's configured read/write access and the Node executable used by probes. It denies all other filesystem reads by default, explicitly denies clilinkapi configuration and Codex home, and disables command network access. Runtime code and authentication remain in the trusted Codex parent; commands must not read credentials. `:minimal` is the pinned Codex platform runtime allowlist, not an arbitrary directory supplied by a client. Protected project metadata is read-only. There is no approval escalation path; server-initiated approvals and interactive questions are refused. Registered dynamic function calls are returned to n8n for execution under its own permissions, with results bound to the original workspace, model, tool definitions and conversation. Web search, browser/computer tools, apps, plugins, hooks, memories, image tools, multi-agent, host skill discovery and workspace-dependency tools are disabled.
+
+Do not confuse Codex's legacy `read-only` mode (primarily write protection) with workspace-only read protection. This clilinkapi uses named filesystem permission profiles. Before a turn, the real app-server `command/exec` probes selected-workspace reading, allowed/denied writing according to access mode, denied reading/writing of harmless sentinels outside the workspace, symlink escape denial, and read denial in a child process. On Linux/macOS, a failed or unparseable probe prevents any model turn. Windows does not run the eligible-platform probes; a refusal test is separate from actual enforcement tests.
+
+Configuration paths are canonicalized. Root workspaces, overlaps and known secret-containing workspaces are rejected. Existing symbolic links and junctions are allowed when their resolved targets remain inside the same workspace. `provider.allowSymbolicLinks=false` rejects them. Broken links, directory cycles, external targets and hard-linked files are rejected. This scan is only defense in depth: the native profile must enforce paths for shell commands, newly created links, traversal and descendants at execution time. The clilinkapi does not accept arbitrary filesystem APIs from clients. A trusted operator must not replace workspace directories, alter OS policies, add secrets, or install host configuration while the clilinkapi runs. Use a dedicated OS account with no unrelated project access as additional protection. This is not a hardened hostile-local-user service.
+
+Outstanding qualification limits:
+
+- No successful authenticated end-to-end execution was possible on the available host. Real model phase events, quota handling and live edits still need qualification with that runtime login.
+- Built-in tool enforcement, runtime-resource allowlists, every escape vector, external filesystem mounts, and process cleanup must be reviewed on each supported OS. The included native probes sample critical boundaries; they are not a proof against all sandbox vulnerabilities. Do not deploy to untrusted tenants based on unit tests.
+- Native Windows restricted-token failure is not worked around. The default `provider.allowUnqualifiedWindowsExecution=true` setting skips the platform gate and Windows probes without claiming qualification. Permission profiles remain requested, with no unrestricted fallback. Qualifying Windows still requires separate read/write, ACL, junction, subprocess and network verification, plus complete tool-surface qualification.
+- The lock is per process. Run only one clilinkapi instance for a set of workspaces. Separate instances/external editors can conflict; no distributed lock or persistent queue exists. Both read-only and read-write requests take the workspace lock. Disjoint workspaces may execute concurrently.
+- An authenticated caller may request destructive edits inside a read-write workspace. There is no transactional rollback on timeout, cancellation or upstream failure. No automatic retries are safe for such operations.
+- No persistent conversation API: process restarts, session resumption and cross-workspace session sharing are intentionally unsupported.
+- Token usage is omitted when absent, and streaming excludes usage chunks because `stream_options` is unsupported. Model discovery reflects the runtime's visible catalog, not a quota reservation.
+- Output redaction removes known local paths, absolute path-like strings and known clilinkapi secrets, including split deltas. This changes affected final text and can over-redact path-like prose. It is not a substitute for preventing credential access. Never place secrets in prompts or projects.
+- Default logs exclude content, but Codex may keep its own operational logs under the private Codex home. Ephemeral threads reduce session persistence; this is not a promise that Codex leaves no logs or caches. Protect and manage that directory.
+- OS administrators, the trusted clilinkapi/Codex parent processes, npm dependencies, configured runtime resources and the Codex service are trusted. Filesystem probes never read actual credential contents. Broader system-managed Codex policy can reject operation; it must not be weakened to make this clilinkapi run.
+
+The clilinkapi key uses timing-safe SHA-256 digest comparison; all `/v1/*` requests authenticate before request workspace access or Codex invocation. Strict config validation rejects empty/placeholder keys. Setup uses 256 bits of entropy, exclusive creation and private file permissions; rotation is explicit. The real config is gitignored and must be stored outside any allowed workspace. It must also be kept out of repositories generally, logs, shared backups, screenshots and shell history.
+
+

package/docs/verification.md

@@ -0,0 +1,28 @@
+# Verification record
+
+Build host: native Windows, Node 24.16.0, npm 11.13.0, Codex CLI/SDK 0.155.0. Date: 2026-09-18.
+
+Executed during implementation:
+
+- Strict TypeScript type check and production build: passed.
+- Final unit/HTTP/setup suite: **18 tests passed**. Windows isolation refusal: **1 passed**; native Unix probes: **2 skipped on Windows**.
+- Unit and HTTP integration tests against test-only providers, covering authentication before invocation, configuration validation, message translation, final extraction, reported usage, SSE success/error termination, supported model/reasoning validation, unknown workspace/session/path rejection, junction escape detection, cancellation, timeout, concurrency, normalized errors and split-delta redaction.
+- Native Windows fail-closed isolation test. Linux/macOS read-only/read-write sandbox probes are explicitly skipped on Windows.
+- Official runtime login status check: **Not logged in** in the available runtime context. No browser credentials or desktop login material was extracted.
+- Initial native sandbox initialization: **CreateRestrictedToken failed: 87**. Agent execution remains disabled on Windows.
+- The subsequent probe with the clilinkapi's actual restricted-read profile failed with **Restricted read-only access requires the elevated Windows sandbox backend**. The real app-server handshake succeeded and a fresh dedicated home reported no account. Setup and rotation passed real Windows ACL verification after correcting unnecessary owner reassignment.
+- `npm run test:live`: **BLOCKED**, because no private `CLILINKAPI_CONFIG` and ChatGPT-authenticated runtime were supplied. No successful live response, workspace modification or external-read denial is claimed.
+
+Additional reproducible commands:
+
+```sh
+npx tsx scripts/diagnose-runtime.ts
+npm test
+npm run test:isolation
+```
+
+The diagnostic uses a fresh empty Codex home, checks the official app-server handshake/account shape, and on Windows attempts a harmless native sandbox process. It never reads existing authentication files or prints credentials. Setup/rotation tests check generated key entropy, refusal to overwrite, private Unix modes/Windows ACLs, and explicit key rotation.
+
+CI is configured for native Ubuntu/macOS/Windows with Node 22 and 24. CI has not been dispatched from this local workspace. The two Unix native probe tests are required there, not silently replaced by mocks. CI does not perform interactive ChatGPT login.
+
+Remaining acceptance work: obtain a supported ChatGPT login in a dedicated runtime home, qualify native Linux/macOS isolation on those hosts, then run `test:live` and real permitted-edit/denied-read cases through HTTP. Native Windows execution additionally requires implementation/qualification beyond the current platform refusal. A live test failure must be reported as failure, not converted to a fixture response.

package/examples/client.mjs

@@ -0,0 +1,13 @@
+// npm install openai in your client project. Do not log the private config.
+import OpenAI from 'openai';
+import { readFile } from 'node:fs/promises';
+const config = JSON.parse(await readFile(process.env.CLILINKAPI_CONFIG, 'utf8'));
+const client = new OpenAI({ baseURL: 'http://127.0.0.1:3000/v1', apiKey: config.auth.apiKey, maxRetries: 0 });
+const catalog = await client.models.list();
+const model = catalog.data[0]?.id;
+if (!model) throw new Error('No available Codex models');
+const result = await client.chat.completions.create({
+  model, reasoning_effort: 'low',
+  messages: [{ role: 'user', content: 'Summarize the project without modifying files.' }]
+}, { headers: { 'X-Workspace-ID': 'project-a' } });
+console.log(result.choices[0].message.content);

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "clilinkapi",
+  "version": "0.1.0",
+  "description": "Native CLI gateway for a ChatGPT-authenticated Codex runtime.",
+  "type": "module",
+  "bin": { "clilinkapi": "dist/src/cli.js" },
+  "files": ["dist/src/**/*.js", "docs/*.md", "examples/client.mjs", "clilinkapi.example.json"],
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:isolation": "tsx --test test/isolation.integration.ts",
+    "start": "node dist/src/cli.js serve",
+    "clilinkapi": "tsx src/cli.ts",
+    "test:live": "tsx scripts/live.ts"
+  },
+  "dependencies": { "@openai/codex": "0.155.0", "@openai/codex-sdk": "0.155.0", "zod": "^4.0.0" },
+  "devDependencies": { "@types/node": "^22.0.0", "tsx": "^4.20.0", "typescript": "^5.9.0" }
+}