@octelium/console-agent 0.1.0-b-ca02.1.1

package/LICENSE

@@ -0,0 +1,267 @@
+OCTELIUM ENTERPRISE SOURCE-AVAILABLE LICENSE
+Version 1.0
+Copyright (c) 2025-present Octelium Labs, LLC. All rights reserved.
+
+By accessing, copying, modifying, or using the Software, you agree to be bound
+by this License. If you do not agree, do not access or use the Software.
+
+1. DEFINITIONS
+
+   1.1 "Licensor" means Octelium Labs, LLC.
+
+   1.2 "Software" means all source code, compiled code, configuration files,
+       documentation, and associated materials made available in this repository,
+       including any Modifications (as defined in Section 1.7) whether or not
+       such Modifications have been submitted to Licensor.
+
+   1.3 "Commercial Agreement" means a valid, fully executed written agreement
+       between you (or your Organization) and Licensor that expressly grants
+       rights beyond those in this License.
+
+   1.4 "Production Environment" means any system, infrastructure, or deployment
+       that (a) serves external users or customers, (b) processes live or real
+       business data, (c) is part of a revenue-generating activity, (d) acts as
+       a staging, pre-production, testing, or continuous integration/continuous
+       deployment (CI/CD) environment supporting or intended to support the
+       foregoing, or (e) provides network access to or otherwise directly
+       supports systems that meet criteria (a)–(d).
+
+   1.5 "Personal Use" means use solely by a natural person on systems that
+       person personally owns or controls, exclusively for that individual's
+       own non-commercial, non-professional purposes, and not (a) on behalf of
+       or for the benefit of any Organization, employer, or client; (b) in
+       connection with any consulting, contracting, or freelance activity;
+       or (c) to provide services or functionality to any other person or entity.
+       For the avoidance of doubt, any use that is conducted through, on behalf
+       of, or for the benefit of an Organization does not qualify as Personal
+       Use, regardless of whether the individual is the sole owner or operator
+       of that Organization.
+
+   1.6 "Compete" means to develop, market, or operate a commercial product or
+       service that provides functionality substantially similar to the core
+       functionality of the Software, including but not limited to zero-trust
+       network access (ZTNA). This includes using, analyzing, or benchmarking
+       the Software for the purpose of developing such a product or service,
+       whether or not the resulting product contains any code derived from
+       the Software.
+
+   1.7 "Modification" means any work, including source code, patches, bug fixes,
+       improvements, or derivative works, that is based on or derived from the
+       Software or that modifies any file of the Software.
+
+   1.8 "Organization" means any legal entity, including without limitation
+       corporations, partnerships, non-profits, sole proprietorships, and
+       any other form of business, government, or professional enterprise.
+
+   1.9 Commercial Agreement Supersession. If you or your Organization have
+       entered into a Commercial Agreement with Licensor covering the Software,
+       the terms of that Commercial Agreement shall govern your use of the
+       Software and supersede this License to the extent of any conflict.
+
+2. LICENSE GRANT — PERSONAL USE
+
+   Subject to your compliance with this License, Licensor grants natural persons
+   a perpetual, limited, non-exclusive, non-transferable, non-sublicensable,
+   revocable license to:
+
+   (a) access, reproduce, and modify the Software solely to create Modifications
+       for Personal Use; and
+   (b) run the Software and Modifications on systems you personally own or
+       control;
+
+   solely for Personal Use as defined in Section 1.5. This grant does not
+   expire provided your use remains within the Personal Use definition.
+   If your use at any point exceeds Personal Use, this Section 2 grant
+   terminates immediately and Section 3 (or a Commercial Agreement) governs.
+
+   For the avoidance of doubt, any Modification you create under this Section
+   remains subject to this License in its entirety. You may not exercise any
+   rights in your Modification beyond those granted in this Section 2.
+
+3. LICENSE GRANT — ORGANIZATIONAL EVALUATION
+
+   Subject to your compliance with this License, Licensor grants Organizations
+   a limited, non-exclusive, non-transferable, non-sublicensable, revocable
+   license to:
+
+   (a) access, reproduce, and modify the Software solely to create Modifications
+       for internal evaluation purposes; and
+   (b) run the Software and Modifications on systems you own or control;
+
+   solely for internal, non-production evaluation, testing, and proof-of-concept
+   purposes within your Organization.
+
+   For the avoidance of doubt, any Modification you create under this Section
+   remains subject to this License in its entirety. You may not exercise any
+   rights in your Modification beyond those granted in this Section 3.
+
+4. RESTRICTIONS
+
+   Unless you have a valid Commercial Agreement with Licensor expressly
+   permitting the activity, you shall not:
+
+   4.1 Production and Commercial Use. Deploy or use the Software or any
+       Modification in a Production Environment, in connection with a commercial
+       offering, or to generate revenue directly or indirectly.
+
+   4.2 External Provision. Make the Software's or any Modification's
+       functionality available to any third party, including without limitation
+       through a hosted service, software-as-a-service offering, API, or managed
+       service, regardless of whether any copy of the Software or Modification
+       is distributed or transferred.
+
+   4.3 Competitive Use. Use the Software or any Modification, in whole or in
+       part, to Compete with Licensor or to assist any third party in competing
+       with Licensor.
+
+   4.4 Distribution. Copy, distribute, publish, transmit, or make the Software
+       or any Modification available to any third party. For clarity, this
+       prohibits hosting the Software or any Modification in a public repository
+       (e.g., a public GitHub fork), though hosting in a strictly private
+       repository accessible only to individuals authorized under this License
+       for Personal Use or internal Organizational evaluation is permitted.
+
+   4.5 Bypass of License Controls. Remove, alter, or obscure any copyright
+       notice, license notice, or other proprietary marking in the Software
+       or any Modification.
+
+   4.6 Transfer. Assign, sublicense, sell, rent, lease, or otherwise transfer
+       rights in the Software or any Modification without Licensor's prior
+       written consent.
+
+   For the avoidance of doubt, the restrictions in this Section 4 apply to
+   Personal Use licensees to the extent not inconsistent with Section 2.
+   Personal Use does not permit any activity listed in Sections 4.1 through 4.6.
+
+5. MODIFICATIONS — OWNERSHIP AND LICENSE-BACK
+
+   5.1 Your Ownership. As between you and Licensor, you retain copyright
+       ownership of the original creative expression in any Modification you
+       author, subject to Licensor's underlying ownership of the Software from
+       which the Modification is derived.
+
+   5.2 License-Back to Licensor. By creating any Modification, you hereby
+       grant Licensor a perpetual, irrevocable, worldwide, royalty-free,
+       fully paid-up, transferable, sublicensable license under all of your
+       intellectual property rights (including copyright and patent rights)
+       to use, reproduce, prepare derivative works of, distribute, perform,
+       display, and otherwise exploit such Modification in any form and for
+       any purpose, including without limitation incorporation into Licensor's
+       products and services, without any obligation of attribution,
+       compensation, or consent.
+
+   5.3 Moral Rights Waiver. To the extent permitted by applicable law, you
+       hereby irrevocably waive any moral rights or rights of attribution in
+       any Modification you create.
+
+   5.4 Contributor License Agreement. If you wish to formally submit a
+       Modification to Licensor for potential inclusion in the Software,
+       you must first execute Licensor's Contributor License Agreement
+       ("CLA"), available at https://octelium.com/cla. Submissions made without
+       executing the CLA will not be considered. The license-back in
+       Section 5.2 applies regardless of whether a CLA is executed and
+       regardless of whether a Modification is formally submitted.
+
+   5.5 Representation. By creating a Modification, you represent that:
+       (a) you are the sole author of the Modification or have the right
+       to grant the license in Section 5.2; (b) the Modification does not
+       infringe the intellectual property rights of any third party; and
+       (c) if you created the Modification in the course of employment or
+       under contract, you have obtained all necessary permissions from
+       your employer or client to grant the rights in Section 5.2.
+
+6. OWNERSHIP AND RESERVATION OF RIGHTS
+
+   The Software is proprietary to Licensor. All right, title, and interest in
+   and to the Software, including all patent rights, copyright rights, trade
+   secret rights, and other intellectual property rights, are and shall remain
+   the exclusive property of Licensor. No rights are granted to you except as
+   expressly stated in Sections 2 and 3. All rights not expressly granted are
+   reserved by Licensor.
+
+7. FEEDBACK
+
+   If you provide Licensor with suggestions, ideas, bug reports, or other
+   feedback regarding the Software that does not constitute a Modification
+   ("Feedback"), you hereby grant Licensor a perpetual, irrevocable,
+   worldwide, royalty-free license to use, reproduce, modify, and incorporate
+   such Feedback into its products and services without any obligation to you.
+   You retain ownership of your Feedback, but Licensor may use it without
+   restriction or compensation. Feedback that constitutes a Modification is
+   governed by Section 5, not this Section 7.
+
+8. TERMINATION
+
+   8.1 Automatic Termination. This License terminates automatically, without
+       notice, upon your breach of any provision of this License.
+
+   8.2 Effect of Termination. Upon termination: (a) all rights granted
+       hereunder cease immediately; (b) you must promptly destroy or return
+       all copies of the Software and all Modifications in your possession
+       or control; and (c) you must certify such destruction in writing
+       upon Licensor's request.
+
+   8.3 Survival. Sections 5, 6, 7, 8.2, 9, 10, and 11 survive termination.
+
+9. DISCLAIMER OF WARRANTIES
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. TO THE MAXIMUM
+   EXTENT PERMITTED BY APPLICABLE LAW, OCTELIUM LABS, LLC FURTHER DISCLAIMS
+   ALL STATUTORY WARRANTIES. IN NO EVENT SHALL OCTELIUM LABS, LLC OR ITS
+   CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+   IN THE SOFTWARE.
+
+10. LIMITATION OF LIABILITY
+
+    TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+    OCTELIUM LABS, LLC BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+    EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL DAMAGES (INCLUDING LOSS OF PROFITS,
+    LOSS OF DATA, LOSS OF GOODWILL, BUSINESS INTERRUPTION, OR COST OF
+    SUBSTITUTE GOODS OR SERVICES), HOWEVER CAUSED AND UNDER ANY THEORY OF
+    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, TORT, OR OTHERWISE,
+    ARISING OUT OF OR RELATING TO THIS LICENSE OR THE SOFTWARE, EVEN IF
+    ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. OCTELIUM LABS, LLC'S TOTAL
+    CUMULATIVE LIABILITY ARISING OUT OF OR RELATING TO THIS LICENSE SHALL
+    NOT EXCEED ONE HUNDRED U.S. DOLLARS ($100.00). THE FOREGOING LIMITATIONS
+    SHALL APPLY TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, REGARDLESS
+    OF WHETHER LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES,
+    BUT SHALL NOT APPLY TO DAMAGES CAUSED BY LICENSOR'S GROSS NEGLIGENCE OR
+    WILLFUL MISCONDUCT.
+
+11. GENERAL
+
+    11.1 Governing Law. This License is governed by the laws of the State of
+         Delaware, excluding its conflict-of-law rules.
+
+    11.2 Jurisdiction. Each party irrevocably submits to the exclusive
+         jurisdiction of the state and federal courts located in Wilmington,
+         Delaware for resolution of any dispute arising out of this License.
+
+    11.3 Export Compliance. You agree to comply with all applicable export
+         control laws and regulations in connection with your use of the Software.
+
+    11.4 Entire Agreement. This License constitutes the entire agreement between
+         you and Licensor with respect to evaluation and personal use of the
+         Software and supersedes all prior agreements on that subject.
+
+    11.5 Severability. If any provision of this License is found unenforceable,
+         that provision shall be modified to the minimum extent necessary to make
+         it enforceable, and the remainder of the License shall continue in
+         full force.
+
+    11.6 Waiver. Licensor's failure to enforce any provision of this License
+         shall not constitute a waiver of its right to do so in the future.
+
+    11.7 Amendment. Licensor may update this License for future versions of the
+         Software. Your continued use of a version after a license update does
+         not bind you to the updated terms for that version.
+
+THIRD-PARTY COMPONENTS
+
+Certain components of the Software are subject to third-party licenses identified
+in the NOTICES file or within the relevant source files. Such third-party licenses
+govern those components and are not superseded by this License.

package/README.md

@@ -0,0 +1,207 @@
+# @octelium/console-agent
+
+The AI agent behind the chat of the Octelium web console. It runs as an ordinary process inside a Cordium Workspace, uses the Workspace's own Octelium identity and exposes an HTTP/JSON + SSE API that is served as the Workspace's default Application.
+
+```text
+Web console (chat UI)
+   │  HTTP/JSON + SSE (via the Cordium portal, authenticated as the Workspace owner)
+   ▼
+octelium-console-agent ───────────── Cordium Workspace ──────────────────────────────
+   ├─ Pi (agent loop, sessions, compaction, retries, skills)
+   ├─ tools
+   │   ├─ octelium_api_search / octelium_api_describe / octelium_api_call
+   │   │     └─ gRPC over OCTELIUM_AUTH_PROXY_SOCKET (h2c) ──► Octelium APIs
+   │   ├─ present_table / present_chart / present_resources / publish_artifact
+   │   ├─ read / bash / edit / write / grep / find / ls  (the Workspace is the agent's computer)
+   │   └─ web_fetch / web_search
+   └─ LLM ──► Octelium LLM Service (via `octelium connect`), or any Pi provider
+```
+
+## Design
+
+- **Execution.** The agent is a Node.js process inside the Workspace. Everything that the agent does (shell commands, `octelium`/`octeliumctl`, `psql`, `curl`, `kubectl`, scripts) runs with the Workspace's network and filesystem, so the protected Services are reachable by name through the Workspace's `octelium connect`.
+- **Identity.** The Octelium APIs are called through the supervisor's auth proxy socket (`OCTELIUM_AUTH_PROXY_SOCKET`), exactly like the `octelium` CLI does inside a Workspace. Every call is authorized server-side by the Cluster's Policies for the Workspace owner. The model never sees a credential.
+- **API discovery.** The agent embeds a protobuf descriptor set of the Octelium APIs (`apis/octelium.binpb`, generated from the `.proto` files with their doc comments). It powers a BM25 search over ~350 methods, schema rendering with the field documentation, and dynamic invocation: the model sends proto3 JSON, the agent validates it against the descriptors (unknown fields and wrong types are rejected with precise errors), encodes it and calls the method over gRPC. A model can only call a method that exists in the catalog. A compact index of all the methods is part of the system prompt so that common calls need no search.
+- **Approvals.** Methods are classified by risk (`read`, `write`, `destructive`, `sensitive`). Depending on `approvals.octeliumAPI`, non-read calls pause until the User approves them in the UI (and shell commands too if `approvals.bash` is set). Approvals are a UX safety net, not the security boundary: authorization is always enforced by the Cluster.
+- **Model.** By default the model is served by an Octelium LLM Service (`llm.provider: "octelium"`), reached through `octelium connect`, so no provider secret is stored in the Workspace. Any provider supported by Pi (e.g. `anthropic`, `openai`, `google`, `openrouter`) or any compatible endpoint (`custom`) can be used instead.
+- **Backend abstraction.** The HTTP protocol knows nothing about Pi: runs go through the `AgentBackend` interface (`src/agent/types.ts`), so other harnesses (e.g. Codex or Claude as delegated sub-agents) can be added without changing the protocol.
+- **Persistence.** Conversations, finalized messages, Pi sessions, uploads and artifacts are stored in the data directory. An in-flight message is checkpointed and recovered as `interrupted` if the process dies. Restarting the agent resumes the conversations with their full context.
+
+## Running inside a Cordium Workspace
+
+The enterprise `AgentService` (`octelium.api.main.enterprise.v1.AgentService`) provisions the agent of every User on demand: `InitializeAgent` creates the User's personal `octelium.<user>` Cordium Space, its `default` Template and a primary Workspace that serves the agent as its default Application on port `8080`. The Template installs Node.js upon the first start of a Workspace if the image lacks it (`ON_CREATE`) and starts `npx --yes --prefer-online @octelium/console-agent@<version> serve` on every start (`POST_START`). Development builds use their Git branch as the npm tag, falling back to `dev` when build branch metadata is absent. Production uses the Go build's semver, removing a leading `v`, and falls back to `latest` when no valid semver is available. The Template is generated from the `spec.agent` section of the enterprise ClusterConfig:
+
+| Field | Description |
+| --- | --- |
+| `isDisabled` | Disables the `AgentService` |
+| `llm.service`, `llm.model` | The default LLM Service and model (i.e. `llm.service` and `llm.model` below) |
+| `version` | Development override for the `@octelium/console-agent` npm tag or version; production uses the Go build's semver or `latest` |
+| `image`, `limit` | The Workspace image and compute resources |
+| `config` | Any additional configuration (same structure as `config.json`), passed via `OCTELIUM_CONSOLE_AGENT_CONFIG_JSON` |
+
+The Workspaces themselves are started, stopped, watched and deleted via the Cordium `MainService` (the web console does so from its `/agent` page). The agent can also run in any other Workspace whose image has Node.js 22.19+ and `git`, for example with such a Template:
+
+```yaml
+spec:
+  runtime:
+    envVars:
+      - key: OCTELIUM_CONSOLE_AGENT_CONFIG_JSON
+        value: '{"llm":{"service":"llm.default","model":"gpt-5.1"}}'
+    tasks:
+      - name: console-agent
+        type: POST_START
+        isBackground: true
+        run: npx --yes --prefer-online @octelium/console-agent@latest serve
+  applications:
+    - name: agent
+      displayName: Octelium Agent
+      port: 8080
+      isDefault: true
+```
+
+`npx … doctor` checks the configuration, the Octelium API access and the LLM access.
+
+`make build-apiserver` embeds the current Git branch and release tag in the API server. Production checks the build's `SemVer` first, then its `GitTag`, and uses `latest` if neither contains a valid semver. The Cluster's usual development/production detection selects the agent version; `OCTELIUM_DEV=true` forces development and `OCTELIUM_PRODUCTION=true` forces production. The npm tag or version must already be published. Branches outside `main`, `dev` and `b-*` can be published manually with their branch name as the npm tag, or use `spec.agent.version: dev` during development.
+
+The `--prefer-online` flag checks for tag updates at every Workspace start. After changing the Cluster's agent configuration or upgrading from the fixed-version launcher, call `InitializeAgent` to reconcile its Template, then restart the Workspace to run the selected package version.
+
+## Configuration
+
+The configuration is read, in increasing precedence, from the defaults, a JSON file (`--config`, `OCTELIUM_CONSOLE_AGENT_CONFIG` or `<dataDir>/config.json`), the `OCTELIUM_CONSOLE_AGENT_CONFIG_JSON` environment variable (convenient for Workspace env vars and Secrets) and the CLI flags. Unknown fields are rejected. See `config.example.json`.
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `dataDir` | `~/.octelium-console-agent` | Conversations, sessions, uploads, artifacts, skills |
+| `workDir` | `/workspace` if it exists, else `$HOME` | The agent's working directory |
+| `logLevel` | `info` | `debug`, `info`, `warn`, `error` |
+| `server.host`, `server.port` | `0.0.0.0`, `8080` | Listen address (`8080` is the portal's default Application port) |
+| `server.allowedOrigins` | `https://console.octelium.<domain>`, `https://$CORDIUM_HOSTNAME` | Accepted `Origin` headers (plus the request's own origin) |
+| `server.cors` | `false` | Emit CORS headers. Keep it off when the Cluster ingress already handles CORS |
+| `server.authToken` | | Optional bearer token (or `?access_token=`) required for `/v1/*` |
+| `server.maxUploadBytes` | 100 MiB | Upload limit |
+| `octelium.mode` | `auto` | `proxy` (auth proxy socket), `direct` (`OCTELIUM_DOMAIN` + `OCTELIUM_ACCESS_TOKEN`, for development), `disabled` |
+| `octelium.domain` | `OCTELIUM_DOMAIN` | Cluster domain |
+| `octelium.timeoutSeconds` | `30` | Per-call deadline |
+| `llm.provider` | `octelium` | `octelium`, `custom` or any Pi provider ID |
+| `llm.service` | | The LLM Service (`name` or `name.namespace`). Its URL is resolved via the User API |
+| `llm.baseUrl` | | Overrides the endpoint (required for `custom`) |
+| `llm.api` | `openai-completions` | Pi API of the endpoint, e.g. `openai-responses`, `anthropic-messages`, `google-generative-ai` |
+| `llm.model` | | Model ID. Discovered from the endpoint's model list if unset (`octelium`/`custom`) |
+| `llm.apiKey`, `llm.apiKeyEnv` | | Provider credentials. Not needed with an Octelium LLM Service |
+| `llm.thinkingLevel` | `medium` | `off` … `max` |
+| `llm.contextWindow`, `llm.maxTokens`, `llm.reasoning`, `llm.input` | from Pi's catalog | Model metadata for unknown model IDs |
+| `llm.loginProviders` | `anthropic`, `openai` | The Pi providers that the Users can sign in to with their own subscriptions (Claude Pro/Max, ChatGPT) |
+| `agent.tools` | all | Pi built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` (`grep`/`find` are dropped if `rg`/`fd` are missing) |
+| `agent.systemPromptAppend` | | Extra instructions |
+| `agent.loadContextFiles` | `false` | Load `AGENTS.md`-style files from the working directory |
+| `agent.maxConcurrentRuns` | `4` | Across conversations |
+| `agent.sessionIdleTimeoutSeconds` | `1800` | Idle Pi sessions are disposed (and transparently reopened) |
+| `agent.compaction`, `agent.maxRetries` | `true`, `3` | Context compaction and LLM retries |
+| `agent.generateTitles` | `true` | Generate conversation titles with the LLM |
+| `approvals.octeliumAPI` | `write` | `never`, `destructive` or `write` (writes, deletions and sensitive calls) |
+| `approvals.bash` | `false` | Require an approval for every shell command |
+| `skills.repositories` | `octelium/octelium-skills@main` | Agent Skills repositories, cloned/updated at startup (best effort) |
+| `skills.paths` | | Local skill directories |
+| `webSearch` | | `{"provider": "brave" \| "tavily" \| "searxng", "baseUrl", "apiKey" \| "apiKeyEnv"}`. `baseUrl` can point to an Octelium Service for secretless access |
+
+### Models and subscriptions
+
+The model can be switched at runtime (`PUT /v1/model`). The selection is saved in `<dataDir>/settings.json` and takes precedence over `llm.*` as long as its provider stays configured.
+
+A User can also sign in with their own Claude or ChatGPT subscription from the web console. The OAuth flows run inside the agent (`/v1/auth/logins`): the console shows the provider's sign-in link and then sends back what the provider shows after signing in (the code, or the URL of the page it redirected to, which never needs to load since it points to the Workspace's `localhost`). The tokens are stored and refreshed by Pi in `<dataDir>/pi/auth.json` inside the Workspace and never leave it. Once signed in, the agent switches to the provider's default model.
+
+## HTTP API
+
+All the types are exported from `@octelium/console-agent/protocol` (`src/protocol/index.ts`), which has no runtime dependencies and is meant to be imported by the web console.
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | `/healthz` | Liveness |
+| `GET` | `/v1/info` | Version, protocol version, model, identity, capabilities, issues |
+| `GET` | `/v1/conversations` | List the conversations |
+| `POST` | `/v1/conversations` | Create a conversation, optionally starting a run: `{"title"?, "input"?: {"text", "attachments"?}}` |
+| `GET` | `/v1/conversations/{id}` | The conversation, its messages and the snapshot of its active run |
+| `PATCH` | `/v1/conversations/{id}` | Rename: `{"title"}` |
+| `DELETE` | `/v1/conversations/{id}` | Cancel its run and delete it |
+| `POST` | `/v1/conversations/{id}/runs` | Start a run: `{"input": {"text", "attachments"?}}` (`409` if a run is active) |
+| `GET` | `/v1/runs/{id}` | Run snapshot (run + in-progress assistant message) |
+| `GET` | `/v1/runs/{id}/events` | SSE stream of the run's events |
+| `POST` | `/v1/runs/{id}/cancel` | Cancel the run |
+| `POST` | `/v1/runs/{id}/approvals/{approvalId}` | `{"decision": "approve" \| "reject", "reason"?}` |
+| `POST` | `/v1/files?name=<file name>` | Upload a file (raw body). Returns a `FileInfo` whose `id` can be attached to a run |
+| `GET` | `/v1/artifacts/{id}` | Artifact metadata |
+| `GET` | `/v1/artifacts/{id}/content` | Download an artifact (`attachment`, sandboxed CSP; `?inline=1` for safe types) |
+| `GET` | `/v1/models` | The current model, the thinking level and the available models |
+| `PUT` | `/v1/model` | Switch the model: `{"provider", "id", "thinkingLevel"?}` |
+| `GET` | `/v1/auth/providers` | The subscription providers and whether they are signed in |
+| `DELETE` | `/v1/auth/providers/{id}` | Sign out |
+| `POST` | `/v1/auth/logins` | Start signing in: `{"provider", "selectModel"?}`. Returns a `LoginSession` |
+| `GET` | `/v1/auth/logins/{id}` | Poll a `LoginSession` (`events` such as `auth_url`, the pending `prompt`, `status`) |
+| `POST` | `/v1/auth/logins/{id}/prompts/{promptId}` | Answer the pending prompt: `{"value"}` |
+| `DELETE` | `/v1/auth/logins/{id}` | Cancel signing in |
+
+Errors are `{"error": {"code", "message"}}`. `POST`/`PUT`/`PATCH` bodies must be `application/json`.
+
+### Messages and blocks
+
+A run appends one user message and one assistant message to the conversation. A message is an ordered list of typed blocks:
+
+| Block | Content |
+| --- | --- |
+| `markdown` | GitHub-flavored Markdown (streamed). Resources are linked as `octelium://resource/<apiVersion>/<Kind>/<name>` (see `formatResourceURI`/`parseResourceURI`) |
+| `thinking` | The model's reasoning (streamed), possibly `redacted` |
+| `tool` | A tool call: `name`, human `title`, `status` (`pending`, `running`, `awaiting_approval`, `completed`, `failed`, `rejected`, `cancelled`), `input`, truncated `output` and structured `details` (`octelium_api` with the method, risk, request, response and the referenced resources; `command`; `file` with diffs) |
+| `approval` | A pending/decided approval with its risk and a preview of the request or command |
+| `table` | Columns (with types and units) and rows |
+| `chart` | `line`, `area`, `bar`, `pie` or `scatter` with an x key, series and rows |
+| `resources` | Resource references with their console URIs and, when known, a snapshot |
+| `artifact` | A downloadable file published by the agent |
+| `notice`, `error` | Informational notices (e.g. context compaction) and errors |
+
+Clients must ignore unknown block types and unknown fields, which is how new block types are added without breaking older consoles. `PROTOCOL_VERSION` is bumped for incompatible changes only.
+
+### Events
+
+`GET /v1/runs/{id}/events` streams `AgentEvent`s as SSE (`id` is the event's `seq`, `event` its `type`). The events of a run are replayed from the start, or after `Last-Event-ID` / `?after=<seq>`, so a client can reconnect or attach to a run in progress after loading `GET /v1/conversations/{id}`. The stream ends after a terminal run event; a finished run with nothing left to replay returns `204`, which stops `EventSource` from reconnecting.
+
+| Event | Payload |
+| --- | --- |
+| `run.started`, `run.updated`, `run.completed`, `run.failed`, `run.cancelled` | `run` (status, `activity` such as retrying/compacting, usage, error) |
+| `message.created`, `message.completed` | `message` (the completed message is authoritative) |
+| `block.created`, `block.updated` | `messageId`, `block` (full block) |
+| `block.delta` | `messageId`, `blockId`, `text` to append to a `markdown`/`thinking` block |
+| `conversation.updated` | `conversation` (e.g. its generated title) |
+
+## Requirements on the Cluster side
+
+- The Workspace owner must be authorized to access the LLM Service, which is reached through the Workspace's `octelium connect`.
+- The web console calls the agent at the Workspace's hostname through the Cordium portal. Since that is a different origin than the console's, the portal Service allows exactly the console's origin (`https://console.octelium.<domain>`) with credentials. `allowClusterServices` is deliberately not used since it would let any Workspace Application in the Cluster read the agents of other Users.
+- Do not share the agent's Application with other Users: the agent acts with the Workspace owner's identity.
+
+## Publishing
+
+`.github/workflows/publish-console-agent.yaml` publishes the package using npm trusted publishing (GitHub OIDC). Configure the package's trusted publisher on npmjs.com with GitHub organization `octelium`, repository `octelium-ee`, workflow filename `publish-console-agent.yaml`, no environment, and permission to run `npm publish`. No npm token secret is required.
+
+Every push to `main`, `dev` or `b-*` publishes a unique prerelease under the branch's npm dist-tag. For example, workflow run `123`, attempt `1`, on `dev` publishes `0.1.0-dev.123.1` as `@octelium/console-agent@dev`. The base version comes from `package.json`; retries receive a new version because npm versions cannot be overwritten.
+
+Pushing a `v*.*.*` Git tag or publishing a GitHub release publishes the tag's semver, removing the leading `v`. Stable releases use `latest`; semver prereleases and GitHub prereleases use `next`. Tag pushes also cover releases created by the repository's release workflow using `GITHUB_TOKEN`. Automatic runs skip versions already published by another event or an earlier run.
+
+To publish manually, run the workflow from GitHub Actions, select the branch or Git tag and supply the npm `tag`. An optional `version` sets an explicit semver. Without it, a selected Git tag supplies the version, while a selected branch produces a unique prerelease containing the manual npm tag. An explicit version must not already exist on npm.
+
+Run `npm run test:publish` to check publishing version resolution.
+
+## Development
+
+```bash
+npm ci
+npm test              # node:test, no network needed (faux LLM + mock gRPC server)
+npm run typecheck
+npm run build         # dist/
+npm run dev           # node src/cli.ts serve
+node src/cli.ts api search "workspace snapshot"
+node src/cli.ts api describe core.v1.MainService/CreateService
+```
+
+Outside a Workspace, set `OCTELIUM_DOMAIN` and `OCTELIUM_ACCESS_TOKEN` to use the direct mode.
+
+`apis/octelium.binpb` is regenerated by `make gen-api` (or `make gen-api-console-agent` after `make cp-pb`).

package/dist/agent/pi/auth.d.ts

@@ -0,0 +1,32 @@
+import type { AuthEvent } from "@earendil-works/pi-ai";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { Logger } from "../../log.ts";
+import type { AuthProvider, LoginEvent, LoginSession, ModelInfo, StartLoginRequest } from "../../protocol/index.ts";
+import type { AuthController } from "../types.ts";
+export interface AuthManagerOptions {
+    modelRuntime: ModelRuntime;
+    dataDir: string;
+    logger: Logger;
+    providers: string[];
+    onLogin?(provider: string, selectModel: boolean): Promise<ModelInfo | undefined>;
+    onLogout?(provider: string): Promise<void>;
+}
+export declare const toLoginEvent: (event: AuthEvent) => LoginEvent;
+export declare class AuthManager implements AuthController {
+    private opts;
+    private providers;
+    private logins;
+    constructor(opts: AuthManagerOptions);
+    getDeviceId(): string;
+    listProviders(): Promise<AuthProvider[]>;
+    startLogin(req: StartLoginRequest): LoginSession;
+    getLogin(id: string): LoginSession | undefined;
+    answerLogin(id: string, promptId: string, value: string): LoginSession;
+    cancelLogin(id: string): LoginSession;
+    logout(provider: string): Promise<void>;
+    dispose(): void;
+    private touch;
+    private expire;
+    private runLogin;
+    private prompt;
+}