| 1 | --- |
| 2 | name: sigit-code-cloud-agent |
| 3 | description: "Reference for siGit Code Cloud Agent, the autonomous, sandboxed coding agent (task -> pull request) we are building. Use when working on the agent product surface: the AgentRun lifecycle, the AWS sandbox that runs siGit Code headless, per-run scoped tokens, the GitHostAdapter (sigit.si first, then GitHub/GitLab), or anything that turns a delegated task into a reviewed PR. Distinct from siGit Code Cloud (the hosted chat); see the sigit-code-cloud skill for that." |
| 4 | --- |
| 5 | |
| 6 | # siGit Code Cloud Agent |
| 7 | |
| 8 | **siGit Code Cloud Agent** is autonomous, sandboxed siGit Code that solves an |
| 9 | issue or task in a Git repository and opens a pull request, working in the |
| 10 | background like a human developer. The user delegates a task and walks away; the |
| 11 | agent works on its own and comes back with a PR to review. |
| 12 | |
| 13 | Status: **planning**. The full strategy, architecture, pricing, and roadmap are in |
| 14 | [`docs/product/sigit-code-cloud-agent-plan.md`](../../../docs/product/sigit-code-cloud-agent-plan.md). |
| 15 | The product map (how this sits next to the other products) is in |
| 16 | [`docs/product/product-overview.md`](../../../docs/product/product-overview.md). |
| 17 | |
| 18 | ## Where it fits (and the naming that matters) |
| 19 | |
| 20 | - **siGit Code** — the local agent. The engine. |
| 21 | - **siGit Code Cloud** — the hosted **chat** (interactive, synchronous). Its work |
| 22 | unit is a **session**. See the `sigit-code-cloud` skill. |
| 23 | - **siGit Code Cloud Agent** — this. Autonomous, asynchronous. Its work unit is an |
| 24 | **agent run** (one delegated task -> autonomous work -> PR). |
| 25 | |
| 26 | Load-bearing: **"session" belongs to the chat product; the agent's unit is a |
| 27 | "run".** Never call the agent or its runs "sessions". `/cloud/sessions` is chat |
| 28 | history, not agent runs. |
| 29 | |
| 30 | ## What it is and is not |
| 31 | |
| 32 | - **Engine:** siGit Code, run **headless** in an ephemeral **sandbox** (AWS), with |
| 33 | hosted inference. The agent clones the repo, edits, runs build/test, iterates, |
| 34 | and pushes a branch. The agent loop and tools already exist in `getsigit/sigit`; |
| 35 | the new work is running it headless and the orchestration around it. |
| 36 | - **Repo target:** **sigit.si first**, then **GitHub, GitLab, and other Git |
| 37 | hosts**. Scope is **Git only** (no SVN, Mercurial, or other VCS). Keep clone / |
| 38 | branch-push / PR-open behind a `GitHostAdapter` seam from day one so the agent |
| 39 | is not welded to our own forge. |
| 40 | - **Output:** a **pull request** on the target Git host (a pushed branch + review |
| 41 | surface). A human reviews and merges. The agent never auto-merges. |
| 42 | - **MVP trigger (decided):** from a repo on sigit.si, the user describes a task and |
| 43 | the agent produces a PR. Formal issue-assignment is a fast-follow (needs an |
| 44 | Issues feature and the host adapters). |
| 45 | - **Copilot analog:** the Copilot coding agent (the cloud agent), not Copilot Chat. |
| 46 | |
| 47 | ## Architecture (two planes; inference reused) |
| 48 | |
| 49 | ``` |
| 50 | Control plane (Rails, sigit-si) |
| 51 | AgentRun model (lifecycle) + controller + job |
| 52 | Web "Run agent" UI, live run log (SSE), diff -> PR |
| 53 | Mints per-run scoped tokens (git push + inference), enforces caps/metering |
| 54 | | RunTask (aws-sdk) ^ SSE/webhook: logs, status, diff |
| 55 | v | |
| 56 | Execution plane (AWS) |
| 57 | Ephemeral sandbox (Fargate task v1 -> Firecracker microVM at scale) |
| 58 | clones repo (scoped git token) -> runs siGit Code headless |
| 59 | OPENAI_BASE_URL = https://sigit.si/api/v1 (per-run inference token) |
| 60 | edits / runs build+test -> pushes head branch -> PR via GitHostAdapter |
| 61 | Private subnet, egress allowlist, hard caps (wall-clock, tokens, tool calls) |
| 62 | | /v1/chat/completions (per-run token) |
| 63 | v |
| 64 | Inference (unchanged): Api::V1::ChatCompletionsController -> OndeCloudService -> Onde Cloud |
| 65 | Existing entitlement gate, allowance metering, and identity masking all apply. |
| 66 | ``` |
| 67 | |
| 68 | The agent is "just another client" of the inference endpoint siGit Code Cloud |
| 69 | already operates, so the entitlement / metering / identity-masking path is reused |
| 70 | unchanged. Because the agent's inference token is minted server-side per run with |
| 71 | a budget, there is no public client holding credentials, which also closes the |
| 72 | standing "inference token <-> Onde Cloud auth" gap for this path. |
| 73 | |
| 74 | ## Safety (non-negotiable, because it runs code on our infra) |
| 75 | |
| 76 | - Per-run hard caps: wall-clock timeout, CPU/memory, inference token budget (tied |
| 77 | to a new `AgentUsage`), max tool calls, max sandbox lifetime. |
| 78 | - Network **egress allowlist** (sigit.si + package registries only). The single |
| 79 | most important control. |
| 80 | - Ephemeral, **scoped** credentials only; nothing long-lived in the sandbox. |
| 81 | - Human-in-the-loop: the agent opens a PR, never auto-merges. |
| 82 | - Per-plan concurrency caps; real cancellation tears down the sandbox. |
| 83 | - Identity hygiene: run logs, PR titles/bodies, and errors stay neutral (same rule |
| 84 | as chat); never disclose the upstream model or provider. |
| 85 | |
| 86 | ## Pricing shape |
| 87 | |
| 88 | Runs cost sandbox compute (Fargate per-second) **plus** inference tokens, so |
| 89 | metering captures both (`AgentUsage`: runs, agent-seconds, tokens). Sandbox time |
| 90 | is rounding error; price on metered inference per run. Included-run bundles per |
| 91 | plan, mirroring `Subscription::CLOUD_ALLOWANCE`. See the plan doc for the worked |
| 92 | model and the `[FILL FROM PHASE 0]` inputs. |
| 93 | |
| 94 | ## Dependencies / open items |
| 95 | |
| 96 | - **No PRs or Issues on sigit.si yet.** A minimal PR surface is on the critical |
| 97 | path; v1 can ship as "pushed branch + compare view". Issues gate |
| 98 | issue-assignment. |
| 99 | - **AWS is net-new infra** (VPC/IAM/NAT/egress-allowlist). No `aws-sdk` in the app |
| 100 | yet. |
| 101 | - **siGit Code has no headless one-shot mode yet** (TUI or ACP only). Adding a |
| 102 | headless runner that drives the existing loop non-interactively and exits is the |
| 103 | first build step (do not start building until asked). |
| 104 | |
| 105 | ## Status |
| 106 | |
| 107 | Spec and plan only. Nothing built. Do not start implementation without an explicit |
| 108 | go-ahead; this skill is the reference for when we do. |