@jslee124/forge 0.3.0 → 0.3.2

package/resources/docs/en/SECURITY.md

@@ -0,0 +1,272 @@
+# Security Model
+
+简体中文 · Documentation index
+
+## Status
+
+This document defines Forge's implemented security model through Milestone 10.
+Built-in tools stay inside the selected workspace, every valid tool action
+passes through a policy decision, and approval-required actions are denied when
+no approval channel is available. The `safe` and `workspace-write` permission
+profiles are implemented. Persisted sessions restore completed conversation
+only, and every resumed run receives fresh policy and approval state;
+`full-access` remains deferred.
+
+Context checkpoints are derived, untrusted conversation memory. They cannot
+carry approvals, trust decisions, permission profiles, or current verification
+status. Fresh instructions and the current request remain mandatory; the
+canonical transcript is retained separately. Provider-native opaque context is
+treated as sensitive state and is never exposed to plugin observers or ordinary
+trace payloads.
+
+## Principle
+
+Forge is safe by default, but approval is not the same as isolation. The product
+must state which boundaries it enforces and which risks remain with the user.
+
+## Default decisions
+
+| Action | Default decision |
+| --- | --- |
+| Read, list, or search inside the workspace | Allow |
+| First write inside the workspace | Confirm |
+| Later writes covered by the run approval | Allow |
+| Any process command | Confirm |
+| Any registered network tool | Confirm |
+| Any delegated subagent model run | Confirm |
+| Built-in file operation outside the workspace | Deny in v0.1 |
+| Approval-required action without an approval channel | Deny |
+
+Narrow outside-workspace approvals are a possible later feature. They are not
+part of v0.1, so a repository task cannot expand Forge's file-tool boundary by
+asking the user for an exception.
+
+## Permission profiles
+
+### `safe`
+
+The default profile. Workspace reads are automatic. Workspace modifications,
+process commands, registered network tools, and delegated subagent model runs
+require confirmation according to the table above.
+
+### `workspace-write`
+
+Workspace file tools may modify files automatically after the user selects this
+profile. Process commands, registered network tools, and delegated subagent
+model runs still require confirmation, and outside-workspace file access
+remains denied in v0.1.
+
+### `full-access`
+
+Deferred until after v0.1. A future explicit advanced mode would require clear
+warnings and a user decision; a project file or plugin could never enable it
+silently. Forge will not expose a profile whose name implies isolation it does
+not provide.
+
+## Configuration boundary
+
+Forge treats `~/.forge/config.json` as user-controlled configuration. Project
+`.forge/config.json` may override ordinary project behavior but cannot set a
+less restrictive permission profile, mark the project trusted, suppress a
+mandatory approval, increase a user-defined safety limit, or enable a plugin
+from an untrusted project.
+
+API keys, OAuth credentials, and other secrets are invalid in both user and
+project configuration. User configuration may reference a provider or
+credential name, while the secret value comes from an environment variable or
+Forge's owner-readable credential file. ChatGPT subscription credentials stay
+inside Codex App Server's credential boundary.
+
+Forge must validate configuration before loading plugins or starting a run. It
+should warn when user configuration or user-plugin directories have unsafe
+filesystem permissions on platforms where that check is meaningful.
+
+## Filesystem boundary
+
+Built-in file tools resolve canonical paths and symlinks before applying policy.
+Paths inside the selected workspace can follow the active permission profile.
+Paths outside it are denied in v0.1.
+
+Local image attachments are a separate, user-authorized input capability.
+Forge accepts an outside-workspace path only when the user explicitly supplies
+it with `--image`, pastes or drags it into the interactive composer, or selects
+an in-workspace `@` mention. Forge never infers attachments from ordinary
+prompt prose, repository content, or model output. The model's filesystem tools
+remain workspace-confined.
+
+Before encoding a local attachment, Forge resolves its canonical path, requires
+a regular readable file, validates JPEG/PNG/GIF/WebP magic bytes, and enforces
+per-image, combined-size, and count limits. User-supplied HTTP(S) image URLs are
+sent to the selected provider for retrieval; Forge does not fetch them itself.
+Session snapshots and ordinary run events do not persist base64 image bytes.
+
+The policy applies to Forge file tools. It does not automatically constrain a
+child process that has already been approved.
+
+## Process boundary
+
+The v0.1 `run_command` tool accepts a program and an argument array and starts it
+with Node.js `spawn` using `shell: false`. Shell syntax such as pipelines,
+redirection, command substitution, and compound commands is not accepted.
+
+Every process command requires confirmation in the default profile. The
+approval prompt must show at least:
+
+- The exact program and individually quoted arguments
+- The working directory
+- The timeout
+- The requested environment changes, when relevant
+
+Starting a process with its working directory inside the workspace does not stop
+it from reading or writing elsewhere. Without an operating-system sandbox,
+Forge cannot claim filesystem or network isolation for an approved child
+process. `shell: false` stops Forge itself from parsing shell expressions; it
+does not prevent an approved program, such as a package manager, from starting
+other processes or interpreting its own scripts.
+
+## Network boundary
+
+The runtime distinguishes registered network tools from workspace reads. A
+plugin must declare `network:access` before registering a `network`-risk tool,
+and every such model call requires confirmation under both `safe` and
+`workspace-write`. Non-interactive runs deny it when no approval channel is
+available.
+
+The checked-in `web-tools` example additionally restricts protocols and ports,
+checks initial and redirect host addresses, blocks local/private/reserved
+ranges, accepts readable MIME types only, and bounds redirects, time,
+downloads, and retained output. Those checks reduce accidental SSRF and
+resource exhaustion, but they cannot provide OS-level network isolation or
+fully eliminate DNS rebinding between validation and connection.
+
+An approved process command or trusted plugin code may still access the network
+directly with the permissions of the Forge process. Manifest capabilities gate
+Forge registration APIs; they do not constrain arbitrary Node.js calls. The UI
+and documentation must not imply otherwise.
+
+## Delegated model runs
+
+Subagent tools use the separate `model` risk and require confirmation on every
+call, including under `workspace-write`, because they incur another model run.
+The approval view shows the generated tool name and delegated task. The host
+creates the child adapter and never exposes credentials to the plugin.
+
+Children inherit the effective parent policy and approval channel, receive only
+declared non-subagent tools, share bounded run/step/tool budgets, use the same
+workspace and abort signal, and return bounded output. Recursive delegation is
+not available. With tracing enabled, child events are stored in a separate
+trace linked by `parentRunId` and `subagentName`; the parent tool result records
+the child run ID. This is runtime containment, not provider or OS isolation.
+
+## Non-interactive operation
+
+If an operation requires approval and no approval channel is available, Forge
+denies the operation unless the user supplied a narrow approval before the run.
+Non-interactive mode must never interpret silence as approval.
+
+The evaluation harness may provide an approval channel that approves only the
+exact program, arguments, working directory, and timeout declared by a fixture.
+It is test infrastructure, not a general bypass.
+
+## Plugin trust
+
+In-process JavaScript plugins are trusted local code. They can call Node.js APIs
+directly and therefore may read files, start processes, or use the network
+outside Forge's tool API.
+
+Forge's plugin API prevents plugins from weakening core policy through supported
+hooks, but this is not isolation from malicious plugin code. Project-local
+plugins require an explicit project-trust decision before loading. Strong plugin
+isolation requires a separate process or operating-system sandbox.
+
+Project trust is keyed by the canonical workspace path and stored outside the
+repository under the user-level Forge home. A repository-controlled `.forge/`
+file cannot mark the project trusted. Forge must not execute code from
+`.forge/plugins/` during discovery or before the user makes that trust decision.
+
+## Repository-provided instructions
+
+`AGENTS.md`, `.agents/`, and non-executable `.forge/` configuration are
+repository-controlled input. They may influence the model and therefore may
+contain prompt injection, but they cannot approve tool calls, enable
+`full-access`, or weaken a core policy decision.
+
+Skills and configuration are not executed merely because they are discovered.
+Skill discovery reads bounded metadata; `load_skill` accepts only registered
+opaque IDs, revalidates canonical roots, non-symlink regular files, and the
+discovered file identity, and returns bounded content. It does not widen the
+workspace `read_file` boundary. Any referenced script or requested action still
+passes through the normal tool, approval, and trace pipeline. Forge records
+Skill discovery, source, selection reason, load rejection, and truncation so
+the user can inspect the effective context.
+
+## Reasoning visibility
+
+Reasoning or thinking content returned by the model provider is visible to the
+user by default. Forge must identify it as provider-supplied content and must not
+claim access to reasoning that the provider did not return.
+
+Reasoning content may contain repository data or other sensitive information.
+Trace persistence and export must use the same redaction policy as model and
+tool events.
+
+## Persistent sessions
+
+Resuming a session restores completed conversation messages, not executable
+authority. Forge creates a new policy instance for every resumed run and never
+restores prior approvals, pending tool calls, child processes, or provider
+continuation metadata. Current user configuration and project instructions are
+loaded again before the next prompt.
+
+Session snapshots and traces are stored outside the repository under
+`FORGE_HOME`. They may contain repository text, diffs, commands, and model
+output, so they are local sensitive data even after configured credentials are
+redacted.
+
+## Credential handling
+
+DeepSeek/OpenAI API keys, access tokens, refresh tokens, authorization codes,
+and PKCE verifiers
+are secrets. They must never appear in prompts, traces, terminal debug output,
+plugin events, crash reports, or repository files.
+
+Forge currently resolves API keys from process environment variables first,
+then from the explicit `$FORGE_HOME/auth.json` fallback. The fallback is stored
+outside the project, written atomically, protected by directory mode `0700` and
+file mode `0600`, and documented as sensitive plaintext storage rather than an
+operating-system keychain. OS credential-store integration remains a preferred
+future improvement.
+
+Provider/model/reasoning selections are ordinary configuration and may be
+saved under `FORGE_HOME`; credentials remain separate. Credential-shaped
+fields and known secret values are redacted before traces and plugin observers
+receive events.
+
+OAuth token refresh must be single-flight so concurrent model requests do not
+race to rotate the same refresh token. Logout clears Forge-owned credentials.
+Forge must not silently import or modify another application's credential file.
+
+For ChatGPT subscription access, Forge delegates OAuth and refresh to the
+official Codex App Server. Forge sends account JSON-RPC requests but never reads
+Codex's credential file or receives its tokens. This account is shared Codex
+state, so the explicit `forge auth logout openai` command may also sign other
+local Codex clients out.
+
+Codex Engine security semantics are separate from the native Forge policy
+kernel. Its `safe` profile maps to Codex read-only sandboxing. Users must select
+`workspace-write` explicitly to let Codex modify the workspace. Codex tool
+events do not pass through Forge's built-in/plugin tool policy or native JSONL
+trace pipeline; the CLI labels this execution path rather than implying they do.
+
+## Out of scope for v0.1
+
+- A hardened operating-system sandbox
+- Guaranteed network isolation
+- Isolation from malicious trusted plugins
+- Reliable prevention of prompt injection
+- Protection after the user explicitly approves a harmful command
+- Treating another application's private OAuth integration as a stable public API
+- Built-in file access outside the selected workspace
+- Shell-language execution and compound shell commands
+
+Packaged product documentation uses a separate allowlisted resource catalog. Search returns opaque, versioned document/section references; reads revalidate the file, content hash, package version, and output budget. The documentation tools reject arbitrary paths and do not widen workspace file access. Skill and documentation text remains untrusted and cannot grant permissions, expose secrets, or authorize commands.

package/resources/docs/en/SESSIONS.md

@@ -0,0 +1,134 @@
+# Persistent Sessions and Run Traces
+
+简体中文 · Documentation index
+
+## Goal
+
+Forge persists enough trusted metadata and completed conversation history to
+continue an interactive chat after the process exits. This is deliberately
+separate from replaying an in-progress tool call.
+
+The core relationship is:
+
+```text
+Session
+|-- completed user/assistant turns
+|-- provider-exposed reasoning summaries for completed assistant turns
+|-- optional derived context checkpoint
+|-- workspace and working-directory metadata
+`-- Run 1 -> events.jsonl
+    Run 2 -> events.jsonl
+    Run 3 -> events.jsonl
+```
+
+A **session** is the user-facing conversation selected by `forge resume` or
+`/resume`. A **run** is one bounded agent-loop execution for one submitted
+prompt. Resuming a session creates a new run inside that session.
+
+## Storage layout
+
+Milestone 6 uses transparent local files rather than a database:
+
+```text
+$FORGE_HOME/
+|-- sessions/
+|   `-- <session-id>.json
+`-- runs/
+    `-- <run-id>.jsonl
+```
+
+Session snapshots use `schemaVersion: 2`; v1 snapshots migrate on load. Trace
+envelopes retain `schemaVersion: 1`. Files are written only under the resolved
+Forge home. Session snapshots are replaced atomically. Run traces are append-only
+while their run is active.
+
+Each session stores:
+
+- Session ID, creation time, and last-updated time
+- Canonical workspace root and the saved working directory
+- Completed user and assistant messages
+- Provider-exposed reasoning text associated with completed assistant messages
+- The ordered run IDs belonging to the session
+- An optional versioned checkpoint with source/tail hashes and provenance
+
+Each trace line is a versioned envelope containing the run ID, optional session
+ID, sequence number, timestamp, and one structured `RunEvent`. Subagent trace
+envelopes additionally carry `parentRunId` and `subagentName`; the parent trace
+links back through the completed delegation tool result.
+
+## Resume behavior
+
+Forge supports:
+
+```bash
+forge resume <session-id>
+forge resume --last
+```
+
+The interactive `/resume` command opens a bounded list of saved sessions for
+the current canonical workspace. Selecting one replaces the empty/current
+conversation with its completed history and continues in that saved session.
+
+Resume follows these rules:
+
+1. Only completed user/assistant turns and their provider-exposed reasoning are
+   restored for display.
+2. A new prompt always starts a new bounded run with a new run ID.
+3. Current configuration and `AGENTS.md` instructions are loaded again.
+4. Approval state is new for every resumed run.
+5. Provider continuation records and partially completed tool calls are never
+   resumed.
+6. A saved session from another workspace is rejected unless the user starts
+   from that workspace explicitly.
+7. Missing or invalid session files produce an actionable configuration-style
+   error without starting a model request.
+8. A valid checkpoint restores the same bounded active view; a stale or invalid
+   checkpoint is ignored without changing the canonical transcript.
+
+This means Forge restores conversation context, not authority or executable
+state. Saved reasoning remains display-only and is not added to the model's
+conversation history. Providers may expose only a reasoning summary, not their
+private internal chain of thought; Forge saves only the text actually emitted.
+For Codex App Server turns, Forge explicitly requests a detailed reasoning
+summary and renders the streamed summary notifications.
+
+## Inspect behavior
+
+`forge inspect <run-id>` reads and validates the corresponding JSONL trace,
+then renders an event timeline plus duration, model steps, tool calls, token
+usage, context-budget categories, retained/omitted messages, estimation error,
+and terminal status. Inspection never executes tools or contacts the model
+provider.
+
+Terminal rendering and trace persistence consume the same `RunEvent` objects.
+The trace is therefore evidence of the runtime path, rather than a second log
+assembled from terminal strings.
+
+## Redaction and safety
+
+Before persistence, Forge redacts configured credential values and recognized
+secret-bearing fields. In particular, `DEEPSEEK_API_KEY` must never appear in a
+session snapshot or run trace.
+
+Run traces may still contain repository contents, diffs, commands, model text,
+and provider-returned reasoning. Files under `sessions/` and `runs/` are local
+sensitive data and must not be committed to a repository.
+
+Session resume does not weaken the existing security model:
+
+- Previous approvals are not restored.
+- A previous permission profile is not trusted as a grant; current user
+  configuration and explicit CLI choices determine the next run.
+- Project files cannot edit session metadata under `FORGE_HOME` through
+  built-in workspace file tools.
+- Inspecting or listing sessions is read-only and performs no model call.
+
+## Deferred behavior
+
+- Resuming in the middle of an active model stream or tool call
+- Branching or forking a session
+- Cross-machine synchronization
+- SQLite indexing
+- Deleting canonical transcript history through a retention policy
+- Cross-provider reuse of provider-native opaque checkpoints
+- Trace encryption

package/resources/docs/en/TROUBLESHOOTING.md

@@ -0,0 +1,256 @@
+# Troubleshooting
+
+简体中文 · Documentation index
+
+Start with the read-only checks below. They reveal most setup problems without
+contacting a model or changing the repository.
+
+```bash
+node --version
+pnpm --version
+pnpm forge --version
+pnpm forge config validate
+pnpm forge config show
+pnpm forge plugins list
+```
+
+Forge requires Node.js 24 or newer and the repository pins pnpm 11.18.0. When a
+command fails, keep the first actionable error line; later provider or session
+errors may be consequences of the same configuration problem.
+
+## Install or build fails
+
+### pnpm wants to replace `node_modules` in a non-interactive environment
+
+Use CI mode so pnpm does not wait for a terminal prompt:
+
+```bash
+CI=true pnpm install --frozen-lockfile
+```
+
+Then rebuild:
+
+```bash
+pnpm build
+pnpm check
+pnpm test
+```
+
+### The global `forge` command does not reflect source changes
+
+`pnpm link:global` links the built CLI, not TypeScript source at runtime. Rebuild
+the checkout:
+
+```bash
+pnpm build
+forge --version
+```
+
+Confirm which executable your shell sees with `command -v forge`. If the link
+is no longer wanted, run `pnpm unlink:global`.
+
+## Configuration is invalid or surprising
+
+Run:
+
+```bash
+pnpm forge config validate
+pnpm forge config show
+```
+
+Common causes are malformed JSON, an unknown field, a missing
+`"schemaVersion": 1`, or a user-only field inside project `.forge/config.json`. Project files may
+set only stricter `limits` and `context` values. The `show` output includes each
+setting's source so an environment or CLI override is visible.
+
+If `FORGE_HOME` is set, Forge does not use `~/.forge` for that process. Check
+the `Forge home:` line before editing a file.
+
+## API authentication fails
+
+### `Missing DEEPSEEK_API_KEY` or `Missing OPENAI_API_KEY`
+
+Open interactive Forge and use `/login` to save a key, or export the named
+variable:
+
+```bash
+export DEEPSEEK_API_KEY="your-api-key"
+# or
+export OPENAI_API_KEY="your-api-key"
+```
+
+Environment values win over `$FORGE_HOME/auth.json`. Inspect the source without
+printing the key:
+
+```bash
+pnpm forge auth status deepseek
+pnpm forge auth status openai-api
+```
+
+If `/logout` reports that an environment variable remains active, unset it in
+the parent shell yourself. A child process cannot edit its parent's
+environment.
+
+### ChatGPT subscription and OpenAI API were confused
+
+They are separate access routes:
+
+- `OPENAI_API_KEY` uses the usage-based OpenAI API through the native Forge
+  Engine.
+- `forge auth login openai` and `forge codex ...` use ChatGPT subscription
+  access through Codex App Server.
+
+Forge never converts one into the other. See Authentication.
+
+### A stored compatible-route key stopped working after an endpoint change
+
+Stored route credentials are bound to the canonical `baseUrl`. Forge refuses
+to send an old key to a different endpoint. Open `/login`, select the route,
+and save a new credential after reviewing the URL.
+
+### Provider request fails before authentication
+
+Errors such as DNS lookup failure, connection refusal, TLS failure, or timeout
+happen before a provider can accept or reject the key. Check network access,
+the route's `baseUrl`, proxy variables, and whether a local server is running.
+Do not rotate or paste credentials until the transport layer is reachable.
+
+## ChatGPT or Codex Engine setup fails
+
+Confirm that Codex CLI is installed and available, then inspect the shared
+account and model catalog:
+
+```bash
+pnpm forge auth status openai
+pnpm forge models list --provider openai
+```
+
+Use device-code login when a browser callback is unavailable:
+
+```bash
+pnpm forge auth login openai --method device-code
+```
+
+`forge auth logout openai` operates on the shared Codex account and may sign
+other local Codex clients out. Forge does not read or repair Codex's credential
+file directly.
+
+## A write, command, network request, or subagent was denied
+
+Under `safe`, the first write in each native run requires confirmation. Every
+process command, registered network-tool call, and delegated model run also
+requires confirmation. Under `workspace-write`, file writes are automatic, but
+the latter three actions still require confirmation.
+
+When stdin/stderr are not TTYs, a one-shot native run has no approval channel;
+confirmation-required actions are denied. This is expected fail-closed
+behavior. Run in a terminal, narrow the task to read-only behavior, or use a
+purpose-built automation/evaluation approval channel. Do not switch profiles
+expecting OS isolation: neither profile sandboxes an approved process.
+
+## A project plugin is listed but skipped
+
+Project plugins are discovered from the canonical workspace root's
+`.forge/plugins/` directory but are not imported before trust. Review the code,
+then use either the interactive `/plugins` panel or:
+
+```bash
+pnpm forge plugins list
+pnpm forge plugins trust
+```
+
+For an explicit non-interactive trust decision:
+
+```bash
+pnpm forge plugins trust --yes
+```
+
+Trust is stored outside the repository and is keyed to the canonical workspace
+path. A copied or moved checkout needs a new decision. User plugins instead
+live under `$FORGE_HOME/plugins` and must be named in `plugins.enabled`.
+
+The Codex Engine owns a separate tool runtime and does not load Forge plugins.
+
+## `web_search` or `web_fetch` is unavailable
+
+These are not built-in tools. They come from the optional checked-in
+`examples/plugins/web-tools` example. Install and enable that plugin explicitly,
+then restart Forge and confirm the startup resource panel lists it.
+
+If requests fail behind a proxy, the example honors `HTTP_PROXY`,
+`HTTPS_PROXY`, and `NO_PROXY` (plus lowercase aliases). Configure an HTTP or
+mixed proxy endpoint, not a SOCKS-only port. Direct and `NO_PROXY` destinations
+retain private/reserved-address checks. See the example README.
+
+## Reasoning is missing or marked unavailable
+
+Forge renders and persists only reasoning text the provider actually exposes.
+Positive reasoning-token usage does not guarantee that the API returned a
+displayable summary or delta. Forge will not invent hidden chain of thought.
+
+Check the selected provider, model, and effort:
+
+```bash
+pnpm forge config show
+```
+
+Then use `/model` and `/effort` to select a capability advertised by the
+provider. If answers stream normally but reasoning is explicitly unavailable,
+the limitation may be upstream rather than a terminal rendering failure.
+
+## Image attachment fails
+
+Forge accepts JPEG, PNG, GIF, and WebP, with at most 8 images, 20 MiB each, and
+40 MiB total. It validates file magic bytes rather than trusting the extension.
+The selected native model must declare image support.
+
+User-pasted or `--image` paths are explicit attachment authorization and may be
+outside the workspace. Model-invoked file tools remain workspace-confined.
+Check for a readable regular file, supported format, size limit, and compatible
+model. Session files do not persist base64 image data.
+
+## Resume cannot find or open a session
+
+Sessions are workspace-bound. Start Forge inside the same canonical repository
+and try:
+
+```bash
+pnpm forge resume --last
+```
+
+Session snapshots live under `$FORGE_HOME/sessions`. Changing `FORGE_HOME`,
+moving the checkout, deleting a snapshot, or corrupting its JSON changes what
+is available. Resume restores only completed turns; it cannot continue an
+interrupted stream or pending tool call.
+
+## Terminal input or rendering looks wrong
+
+- Enter submits.
+- Shift+Enter inserts a newline in supported terminals.
+- Ctrl+J is the portable multiline fallback.
+- Ctrl+C closes a menu first, cancels a run second, and exits only when idle.
+- `NO_COLOR` disables color; redirected output uses plain terminal-safe text.
+
+Forge has specific keyboard handling for VS Code and Ghostty. If a terminal
+cannot distinguish Shift+Enter, use Ctrl+J. Record the terminal name, `TERM`,
+and the exact key behavior when reporting a reproducible issue; do not include
+credentials or private trace content.
+
+## Collect a safe diagnostic bundle
+
+Before opening an issue, capture only non-secret output:
+
+```bash
+node --version
+pnpm --version
+pnpm forge --version
+pnpm forge config validate
+pnpm forge plugins list
+git rev-parse --short HEAD
+```
+
+Also include the command, expected behavior, first actionable error, operating
+system, terminal, and whether the run used Forge Engine or Codex Engine. If a
+native trace exists, `forge inspect <run-id>` can summarize it, but review the
+result before sharing: traces may contain repository text, diffs, commands,
+model output, and provider-exposed reasoning.