orc-ai 0.1.36 → 0.1.40

package/README.md

@@ -61,6 +61,8 @@ On first launch the app sets everything up:
 
 The builds are unsigned: on macOS right-click the app and choose Open the first time, on Windows choose "More info" then "Run anyway".
 
+The sidebar shows the saved execution host, for example `Connected (lab)` or `Connected (local)`. Switching hosts applies to new actions immediately. For a full restart, use **Settings → ORC server → Restart ORC server**; it keeps settings and reconnects the dashboard automatically. Restart closes active terminals and may interrupt running work. Host changes never trigger a restart automatically.
+
 <details>
 <summary>Headless / CLI-only install (servers, Docker, CI)</summary>
 
@@ -122,6 +124,38 @@ orc task list
 
 Open `http://localhost:7700` to use the web dashboard - task board, kanban, flow runs, jobs, memories, sessions, knowledge, and a live chat panel. The same server hosts both the REST API and the prebuilt React SPA, so there is no separate command to run for the UI.
 
+Chat uses the shared agent runtime: Claude through its SDK, Codex through its native
+CLI, and other agents through ACPX. Choose a model from the composer; configure
+model choices, conversation instructions, the ORC MCP connection and automatic
+actions in **Settings → Chat**. Defaults are stored in `preferences.chat` in ORC's
+JSON configuration and apply to new conversations on every device. The model
+dialog shows the current conversation's setup. Claude appends the instructions
+to its coding system prompt; Codex and ACPX receive them as turn instructions.
+Agent and workspace instructions may also apply.
+
+Automatic actions default off: Claude can request approval in chat, Codex uses a
+read-only sandbox, and ACPX follows its agent's native permission policy. Enabling
+automatic actions lets Claude bypass permission prompts and Codex write inside
+its workspace; ORC rules remain enforced. The ORC MCP option adds an authenticated
+connection for Claude and Codex without exposing credentials to the browser.
+Host configuration can include additional MCP servers; choosing host configuration
+does not disable those servers. Other ACPX agents require host configuration.
+
+Use the history icon to continue a saved chat or an ended Claude/Codex coding
+session. Synced sessions use the existing verified repository/commit handoff;
+provide missing checkout details before importing. Native history stays with the
+agent, while chat displays up to 100 recent imported turns. An active source session
+must end before chat resumes it. Resume failures never trigger a fresh session.
+New chats use the API working directory locally or the selected SSH host's home;
+resumed chats retain their execution host and folder. New conversation keeps the
+previous chat in history.
+
+Responses show provider-supplied text, collapsible thinking summaries and tool
+input/results as they arrive, with a responding indicator during quiet periods.
+Some providers emit complete blocks rather than individual tokens. Conversation
+messages and activity are saved in the ORC database. Full-screen mode preserves
+the conversation; phones and tablets use a full-screen chat sheet automatically.
+
 > [!TIP]
 > The database is created automatically at `~/.orc/orc.db` on first run. No setup needed.
 
@@ -197,6 +231,27 @@ The `--mcp-config` flag wires the host agent back to ORC's [HTTP MCP endpoint](#
 
 ## Connect your agent
 
+For coding-agent access, check the installed `spec` CLI bridge first (`spec --help`,
+`spec specs`). It can call ORC's MCP server without configuring MCP separately in
+each agent. Use an existing ORC registration or an inline endpoint for your selected
+installation:
+
+```sh
+spec call --mcp-http http://127.0.0.1:7700/mcp context --data '{"project":"my-app"}'
+spec call --mcp-http http://127.0.0.1:7700/mcp skill_read --data '{"name":"orc-sdlc","project":"my-app"}'
+```
+
+For authenticated servers, use existing secure secret references in spec configuration;
+do not put secrets in command arguments. Use `SPEC_NO_CACHE=1` when refreshing live
+context and effective skills. Direct MCP connections below remain supported when
+already configured. Check the CLI bridge before reporting ORC unavailable.
+
+Lifecycle hooks and MCP registration are separate. The hook examples below record
+session activity; also register ORC in the client's supported MCP configuration
+using `orc mcp` (stdio) or `<origin>/mcp` (HTTP). Preserve existing servers and
+configure authentication privately. Verify tool discovery and a project-scoped
+`context` call in each client; installed hooks alone do not establish MCP access.
+
 ### Claude Code
 
 Add to `~/.claude/settings.json`:
@@ -309,17 +364,18 @@ The task loop automatically picks up queued tasks and spawns worker agents:
 
 ```bash
 # Create a task with a workflow and backend
-orc task add "Implement user auth" --skill orc-coder --backend claude --priority high
+orc task add "Implement user auth" --skill orc-sdlc --backend claude --priority high
 
 # Or batch-create with dependencies via MCP
 task_batch_create({ tasks: [
-  { title: "Design schema", skill_name: "orc-planner" },
-  { title: "Implement API",  skill_name: "orc-coder", blocked_by: [0] },
-  { title: "Review code",    skill_name: "orc-reviewer", blocked_by: [1] }
+  { ref: "design", title: "Design schema", skill_name: "orc-sdlc" },
+  { ref: "api", title: "Implement API", skill_name: "orc-sdlc", depends_on: ["design"] },
+  { ref: "tests", title: "Verify API integration", skill_name: "orc-sdlc", depends_on: ["api"] }
 ]})
 ```
 
 The loop handles concurrency, session resume on feedback, review round limits, stale claim cleanup, and backend routing.
+Each task's configured flow handles its review; a separate review task is unnecessary.
 
 Every task runs a **flow graph** (see [Task flows](#task-flows)); `orc-default` is the build → review → done pipeline described above.
 
@@ -371,6 +427,8 @@ Enable the task loop in `~/.orc/config.json`:
 
 Projects group tasks, memories, and jobs. Set an active project and all commands auto-scope:
 
+Projects can also store an optional Git remote URL in the create/edit dialog or through `--git-remote-url`. HTTPS and SSH addresses are supported without embedded credentials. The address is project metadata; setting it does not clone a repository or change a checkout's remote. Clear it in the editor, send `git_remote_url: null` through the API, or use `orc project update my-app --clear-git-remote-url`.
+
 ```bash
 orc project add my-app -d "Main application"
 orc project use my-app       # set active
@@ -464,7 +522,7 @@ The graph itself is deterministic; only the nodes are agents. That means loops,
 ```bash
 orc flow list                                    # what graphs are available
 orc flow show orc-default              # nodes, edges, limits
-orc task add "Fix the flaky test" --flow orc-default --skill orc-bugfix
+orc task add "Fix the flaky test" --flow orc-default --skill orc-sdlc
 orc flow status <taskId>                         # active nodes + the ledger of outcomes
 orc flow resume <taskId> --outcome approved      # resolve a human gate
 orc flow halt <taskId>                           # stop it and kill live nodes
@@ -508,6 +566,53 @@ orc job add on-change --command "bun run lint"      --trigger watch --watch "./s
 orc job add on-push   --command "bun run ci"        --trigger webhook
 ```
 
+Jobs separate **what runs** from **when it runs**. Choose **Run command**,
+**Run agent**, or **Create task** in the dashboard. Command is required only for
+Run command. Agent jobs save instructions, backend, optional model and explicit
+tool approval; each run links to its tracked session. Task jobs save a task title
+and instructions and link to the created task. **Start the task flow automatically**
+is off by default, so generated tasks wait for a manual flow start.
+The CLI accepts typed actions through `--action-config <json>`.
+
+New jobs are disabled by default. Select **Enable this job immediately** during
+creation or pass `orc job add ... --enable` to opt in. Jobs supports enable/disable
+directly in the list and for selected rows. Projects shares the selection toolbar
+for activate, pause and archive actions; select-all applies only to displayed rows.
+Failed bulk updates remain selected so you can retry them.
+
+### Webhooks
+
+Open **Activity → Webhooks** to see all configured event sources and their connected
+jobs. Create a source without a job, copy its URL and one-time signing secret, then
+register them with the provider. Sources belong to the selected project, or are
+shared across projects when created in All projects.
+
+In **Jobs → New job** (or Edit), choose **Webhook** as the trigger, select an
+existing source or create one inline, and set this job's event/action filters.
+One source can trigger multiple enabled jobs, each with its own filters and action.
+The Webhooks page shows source enablement, connected jobs and recent deliveries,
+including individual run results and links to generated tasks or agent sessions.
+Deleting a job disconnects it while preserving the reusable source.
+
+For command jobs, accepted JSON is passed unchanged on stdin; bounded metadata is
+also available as `ORC_WEBHOOK_*` environment variables. Agent and task jobs receive
+up to 50,000 characters of event data, explicitly marked as untrusted input, alongside
+the configured instructions. Delivery history stores event metadata and a payload
+hash, not the payload body or signing secret; generated tasks and agent prompts can
+contain the supplied event data.
+
+Generic endpoints verify `X-Orc-Signature-256: sha256=<HMAC-SHA256 of the raw body>`.
+Use `X-Orc-Event` for event filtering and `X-Orc-Delivery` (or
+`Idempotency-Key`) for deduplication. GitHub endpoints use
+`X-Hub-Signature-256`, `X-GitHub-Event` and `X-GitHub-Delivery` directly.
+Event names and payload `action` values are configurable, so PR lifecycle,
+reviews, workflow runs, releases, or later providers use the same job trigger.
+
+Signing secrets are encrypted at rest and shown only when an endpoint is created or
+rotated. The receiver is intentionally outside normal ORC bearer authentication;
+the per-endpoint HMAC is its authentication boundary. Management remains under the
+authenticated API.
+
 ### Gateway (Telegram / Slack)
 
 Approve agent work from your phone, search memory, or start a live AI session.
@@ -551,7 +656,7 @@ Same commands as Telegram. Create a Slack app at [api.slack.com/apps](https://ap
 
 ## Skills
 
-ORC ships with agent workflow skills and built-in skill templates for the task loop.
+ORC ships two entry-point skills. Their supporting references load only when needed; custom skills and packages remain supported.
 
 ### Install skills
 
@@ -560,21 +665,23 @@ ORC ships with agent workflow skills and built-in skill templates for the task l
 npx skills add niradler/orc --all
 
 # Or pick specific ones
-npx skills add niradler/orc --skill orc-session orc-tasks
+npx skills add niradler/orc --skill orc-platform orc-sdlc
 
 # Global install
 npx skills add niradler/orc --all -g
 ```
 
-### Agent workflow skills
+### Entry-point skills
 
-| Skill           | Triggers on                                                                |
-| --------------- | -------------------------------------------------------------------------- |
-| `orc-session`   | Session start, context compaction, resuming work                           |
-| `orc-tasks`     | Task creation, status updates, HITL review, task decomposition             |
-| `orc-memory`    | Short project facts, "remember this", "what did we decide"                 |
-| `orc-knowledge` | Searching indexed docs, managing knowledge collections                     |
-| `orc-gateway`   | Telegram/Slack setup, remote approval, live agent sessions                 |
+| Skill | Purpose |
+| --- | --- |
+| `orc-platform` | Operate ORC domains: setup/interfaces/auth, memory and maintained KBs/digests/embeddings, work/operations, sessions/SSH/Git/chat, rules and agent packages |
+| `orc-sdlc` | Requirements → risk/complexity classification → direct work or plan → implementation → tests/completeness → review/rework → authorized Git delivery, with shared learning throughout |
+
+Start with the relevant entry point and read only its selected reference. Platform
+guidance groups related domains while keeping memory, execution and rules independently
+loadable; SDLC has planning, development and review/delivery references. Clear low-risk
+work can execute directly; assigned managed nodes preserve roles and flow contracts.
 
 ### Built-in skill templates
 
@@ -585,7 +692,7 @@ On the **Skills** page, each built-in has an **Agent discovery** toggle, plus
 across the installation and defaults to visible. Hidden built-ins stay on the
 Skills page for management and remain readable by name, including supporting
 files; existing task flows continue to use them. User/imported skills and authored
-global/project instruction overrides remain discoverable.
+global/project instruction overrides of current skills remain discoverable.
 
 The policy is saved under `skills.hidden_builtins` in `~/.orc/config.json` and
 read afresh for discovery, including by existing MCP processes. `GET /api/skills`
@@ -595,16 +702,14 @@ omits hidden built-ins; `include_hidden=true` returns the management catalog wit
 API authentication. This installation-wide preference ignores project config.
 New built-ins default to visible until hidden explicitly.
 
-| Skill              | Type     | Purpose                                                                     |
-| ------------------ | -------- | --------------------------------------------------------------------------- |
-| `orc-worker-base`  | Base     | Default worker behavior - ORC awareness, status updates, deliverable format |
-| `orc-main-base`    | Base     | Orchestration agent - planning, decomposition, monitoring                   |
-| `orc-coder`        | Workflow | Implementation - understand, plan, implement, verify, submit                |
-| `orc-planner`      | Workflow | Task decomposition with dependencies and workflow assignment                |
-| `orc-reviewer`     | Workflow | Structured evaluation - correctness, tests, security, conventions           |
-| `orc-bugfix`       | Workflow | Bug investigation - reproduce, root-cause, fix, regression test             |
-| `orc-requirements` | Skill    | Requirements interview - outcome, criteria, constraints, scope              |
-| `orc-report`       | Skill    | Project status report - health summary, blockers, active work               |
+Retired built-in names (such as `orc-coder` and `orc-reviewer`) remain readable
+as compatibility routes for saved tasks, authored overrides and frozen flows, but
+are not additional discovery entries. New tasks and built-in flows use
+`orc-sdlc`; the node role selects implementation versus independent review.
+Applicable authored legacy worker/coder/reviewer/knowledge instructions remain
+role-scoped supplements with revision provenance, including on resume. Other authored
+legacy domain guidance is indexed from the canonical effective read and loads by name
+when relevant. Conflicts are surfaced rather than silently rewriting stored overlays.
 
 Add custom skills by creating a `SKILL.md` in `~/.orc/skills/my-workflow/SKILL.md`.
 
@@ -629,7 +734,7 @@ orc skill validate ./my-workflow
 orc skill export my-workflow ./exported/my-workflow
 ```
 
-Import public GitHub skills from **Skills → Import from GitHub**. Paste a repository URL, `owner/repo`, a GitHub skill-folder URL, or a `https://skills.sh/owner/repo/skill` link, discover the skills, then select which to import. ORC copies each complete folder at the displayed commit, including nested documentation, scripts and binary assets. Existing names are never overwritten by an import. Select up to 16 skills per import (64 MiB total).
+Import GitHub skills from **Skills → Import from GitHub**. Paste a repository URL, `owner/repo`, a GitHub skill-folder URL, or a `https://skills.sh/owner/repo/skill` link, discover the skills, then select which to import. Private repositories use `gh` credentials on the configured execution host (local by default, remote when `ssh.host` is set), falling back to `ORC_GITHUB_TOKEN` / `github.token` on the ORC server; credentials need access to the repository. Without credentials, public repositories still work. ORC copies each complete folder at the displayed commit, including nested documentation, scripts and binary assets. Existing names are never overwritten by an import. Select up to 16 skills per import (64 MiB total).
 
 ```bash
 orc skill import vercel-labs/agent-skills --list
@@ -670,6 +775,15 @@ The **Agents** page creates/reads specialist profiles. API `/api/agents` and `/a
 
 ## MCP tools
 
+Agents can fetch original skill scripts/assets with
+`skill_read({name: "orc-platform", ref: "scripts/upload-session.py", download: true, project: "my-app"})`.
+It returns a signed ten-minute `download_url`, `sha256`, `size_bytes` and expiry
+instead of the file body. Download to a local file and verify the hash; do not
+reconstruct scripts from tool text. The URL authorizes only that file version and
+does not contain the API secret. Keep it private. Expiry, API restart or file changes
+require a new URL. Downloading never executes scripts. The authenticated REST mint
+endpoint is `POST /api/skills/<name>/download` with `ref` and optional scope.
+
 Tools are available to any connected agent. Start every session with `context`.
 
 | Category      | Tools                                                                                                                                       |