forge

List agent sessions for a project. Optional issueId/status filters. Returns a lightweight projection per session: the heavy jsonb columns (messages transcript, diff, usage, pipelineTelemetry, pipelineHealth, pipelineControl) are OMITTED to stay under the response token cap — `messageCount` exposes t…

Fetch a single agent session. Truncates `messages` to the last 20 entries (totalMessages exposes the full count) so MCP payloads stay bounded. Requires the principal to be a member of the session’s project; PAT principals must additionally have the session’s project in their allowlist.

List the collaborators across your projects (projects you own or are a member of) with a membership matrix scoped to those projects. Read-only. Action: `list` (optional `search` matches email prefix; paginated). Each user includes `memberships: [{ projectId, projectSlug, role }]` limited to your vis…

Server snapshot: version, uptime, db/queue/ws status, last builtin-skills seed result, and active jobs count. No project scope.

List jobs scoped to a project (default 25, max 200; ordered newest-first). Supports status/type/issueId filters. Returns a lightweight projection per job: the heavy fields (payload, promptBlocks, failureMeta jsonb and the unbounded userPromptSnapshot/error text) are OMITTED to stay under the respons…

Fetch a single job by id including its linked agentSessionId. A `queued` job also carries `gate`: `{ ok: true }` when it is dispatchable and merely awaiting its turn, or `{ ok: false, reason }` naming the gate holding it — the answer to "why has this been queued for days?", which `status` alone cann…

Cancel a single job (audited manual intervention). queued/held → cancelled; dispatched/running → cancellation requested + device push. Cancelling a `held` step leaves its issue and run untouched — reach for this instead of cancelling the whole run, which additionally parks the issue at on_hold. Work…

Put a `held` job back in the queue (audited manual intervention). Use this when the hold's cause is FIXED — `retry_rounds_exhausted` and `non_retryable_terminal` never clear on their own, so without a resume the only way out of one is to cancel the step and lose it. The resume does not re-check the …

Search project memory (issues, comments, jobs, notes, knowledge, decisions, policies). A semantic or hybrid search costs one embedding call (`embedMs` in the result names what it took, `took_ms` the whole); a keyword search costs none. When the question names an issue key, a status or a count, answe…

List memory rows for a project, filtered by source / sourceRef / metadata containment. Returns rows sorted by createdAt|updatedAt|embeddedAt + a total count. Does NOT embed — use for natural-key lookups (e.g. step handoff by run_id+step+attempt). Live rows only unless includeArchived:true, which als…

Delete a memory row by (projectId, source, sourceRef). Idempotent — returns {deleted:false} when no row matches. Requires project membership.

Report the outcome of verifying a memory row against live code/state. verdict=confirmed stamps last_verified_at (protects the row from usage decay); verdict=outdated archives the row immediately (evidence required — what disproved it; a fresh write to the same sourceRef revives it). Agent-curated so…

Write (upsert) a memory row for a project. Embeds textContent via the configured embedding model and stores under the unique key (projectId, source, sourceRef) — the ref you name is ALWAYS the ref that is written, and no other row is ever modified. Re-writing an existing ref REPLACES its body; the b…

Aggregated pipeline-step durations (p50/p95/avg/cost/sample size) for one project over `pipeline_run_step_durations`. Requires project membership. Filterable by `days` (1..90, default 30) and `step`. Returns `{ rows: [{ step, p50, p95, avg, totalCostUsd, n }], windowDays, projectId }`. Pass `breakdo…

Project time-series trend for the v2 dashboard charts (ISS-380). Returns a dense (gap-filled) bucketed series for one `metric` of cost | throughput | cycle_time | queue_wait | runner_utilization | cache_hit_rate, derived entirely from existing tables. Requires project membership. Params: `projectId`…

Retry failures later rescued by a successful retry, reconstructed from historical job chains. Requires project membership. Groups results by the original failure reason. Params: `projectId` and `days` (1..90, default 30). Returns `{ rows: [{ failureKind, failureReason, rescues, lastRescuedAt }], tot…

Failed agent sessions grouped by ISS-877 failure cause. Requires project membership. Params: `projectId` and `days` (1..90, default 30). Counts sessions whose STATUS is `failed` or `cancelled_stale`. Returns `{ rows: [{ cause, origin, sessions, isRealFailure, lastAt }], total, unclassified, unclassi…

List organizations the calling principal belongs to, with the caller's org role (owner|admin|member) and the isPersonal flag. Use the id as `orgId` for forge_projects.create or org-owned integration connections. Org management (create/members) lives on REST /api/orgs.

List the members of an org the calling principal belongs to (userId, email, role, createdAt). Non-members read NOT_FOUND.

Declare which phase of an autonomous run you are in. Call action `start` BEFORE beginning a phase (understand, plan, code, self-review, review, merge, ship) and action `end` when it finishes, with `outcome` one of ok/failed/abandoned. The `start` call returns the `attempt` number to pass back to `en…

[DEPRECATED — use forge_project_pipeline_runs (action=get)] Fetch a single pipeline run plus a per-status job count breakdown. Requires the principal to be a member of the run’s project; PAT principals must additionally have the run’s project in their allowlist.

List projects visible to the principal (explicit project membership of any role, plus org owner/admin implicit access). For PAT principals, results are additionally narrowed to the token's projectIds allowlist when set. Returns id, slug, name, orgId, role (effective: admin|member|viewer).

Create a new project in an org (orgId optional — defaults to the caller's personal org; the caller becomes a project admin). Accepts slug+name plus optional initial description/repoPath/baseBranch/productionBranch. PAT principals must carry the `write` scope and have a null `projectIds` allowlist (s…

Update project settings (name, description, repoPath, baseBranch, productionBranch, kind). `kind` is the project's SHAPE, not a label: `website` means an Epodsystem-backed storefront where the store is the source of truth and a git repo is optional, and the runner then skips the git preflight and th…

Fetch project detail visible to the principal — id, slug, name, description, orgId, createdBy, role (effective: admin|member|viewer), repoPath, workspaceSetup, baseBranch, productionBranch, defaultDeviceId, previewDeploy.{stagingUrl,stagingApiUrl,testingUrls,testCredentials,notes}, createdAt. `works…

Update Pipeline stage ② (Reconcile) tool. Actions: - trigger: Start a reconcile run for a skill × packet pair (admin-only). Enforces C1–C5 contract. Returns runId or a structured refusal. - get: Fetch a single reconcile run by runId (member-gated). Returns run status, verdict, gate, bundle snaps…

Manage runners for projects in your scope (projects you own or are a member of). Actions: `list` (optional projectId/status/type filters, restricted to your projects; returns inFlightCount per runner plus quarantinedUntil/quarantineReason — non-null means the box is HARD-excluded from dispatch after…

List Forge Facts — the FIXED Forge process knowledge a skill author references instead of copy-pasting (status ladder, complexity/priority/category enums, relation kinds, plan/release-notes/handoff formats, worktree protocol). Each fact carries id, tier (`mandatory` = always injected; `contextual` =…

Fetch one Forge Fact by id (project-resolved), returning its full canonical `preview` text — the exact block a skill body gets when it references `{{forge:<id>}}`. Pass optional `stage` for stage-specific facts. Throws NOT_FOUND for an unknown id. Requires project membership.

Catalog of skills visible to a project, deduped by name. Returns a lightweight projection per skill (catalog metadata + dedup hints); the heavy bodies (skillMd, prompt, files, tools, manifest, changelog, localGuide) are OMITTED to stay under the response token cap — fetch a skill body via forge_skil…

Fetch a single skill by id. Returns null when the skill is project-scoped to a different project (no cross-project leak).

Bind a PROJECT skill to a pipeline stage for this project (or clear with stage=null). Only project-scoped skills may be registered — a global template must be adopted (forge_skills.adopt) into the project first, else this rejects with SKILL_NOT_PROJECT_SCOPED. Requires project owner/admin.

List the project's stage→skill bindings overlaid with per-stage `enabled` and `mode` from `agentConfig.pipelineConfig.states`. `enabled` applies at every stage. `mode` ('auto'|'manual') gates at the ENTRY status alone — it decides whether a human releases work before it starts — and comes back `null…

Create a project-scoped skill (folder-first: a SKILL.md body + optional supporting files[]). Use this to load a local skill into Forge as the source of truth. Returns the created skill row (with id, version, contentHash). Requires owner/admin on the project. Global skills cannot be created here.

Update a project-scoped skill (name/description/skillMd/target/files/localGuide/installOnly). Bumps version + recomputes contentHash when the body or files change. Set installOnly:true to force-sync a manual / user-invocable utility skill to runners WITHOUT binding it to a pipeline stage — it enters…

Delete a project-scoped skill. Requires owner/admin. Global skills cannot be deleted here.

The project's CATALOG — deduped by name: project skills (scope='project', USABLE) plus global TEMPLATES (scope='global', adoptable, NOT usable). Each row carries skillMd, files, effectiveHash, scope, and shadowsGlobal/shadowedGlobalSkillId (catalog hints only). NOTE: this is NOT what a device instal…

Adopt a global skill TEMPLATE into this project: clones the global (skillId must be a global) into a new project-scoped skill of the same name, which the project then owns and can edit + register. This is the ONLY way a global enters a project at runtime (globals never install/dispatch directly). Re…

Per-device skill freshness for the project: for each device-bound runner and each registered skill, whether it is synced / outdated / missing (server effectiveHash vs the device-reported installedHash) plus syncedAt. Use after a push to verify a device picked up the new skills. Requires project memb…

Push (sync) the project's skills to its device-bound runners. Sends a `skill.sync` command over WebSocket to each targeted device room; the device pulls its effective manifest and reports installed hashes back — bodies are NOT sent in this call. Omit deviceId to signal every device-bound runner of t…

Upsert a step handoff (structured pipeline-state output) for an issue. Stores `payload` under `kind='handoff'` keyed on (issueId, step, attempt). Validates payload via the per-step discriminated schema. Requires project membership.

List step handoffs for an issue. Filter by pipelineRunId and/or `steps` allow-list. Returns rows sorted by createdAt (default desc). Requires project membership.

Delete a step handoff by (issueId, step, attempt). Idempotent — returns {deleted: false} when no row matches. Requires project membership.

Check in at the start of work on an issue. Never moves the issue — pass `stage` and it returns the working bundle: the issue (with `attachments[]`), the most-recent comments, the latest step handoffs, and the resolved `branchConfig` (issue override layered over project defaults — null means NOT conf…