---
name: gentic-code
description: "A Mother capability, not a connect-it-yourself MCP. Mother runs self-contained data and scripting tasks — analyses, transforms, generated artifacts — inside an isolated, network-blocked sandbox on your uploaded inputs, then returns the output plus the code and a verified diff for you to review. Propose-only: nothing deploys, pushes, or writes to your systems without your approval. No access to your repos or storefronts in this release."
license: MIT
metadata:
  author: gentic
  version: "1.0.0"
---

# Gentic Code

Ask Mother for something that needs real code — compute cohort LTV from an orders export, dedupe a customer list, turn a messy CSV into a clean chart — and Mother runs it in an isolated sandbox and hands you back the result plus the code as a reviewable artifact. Nothing of yours is touched: the sandbox has no network, no secrets, and no access to your stores or repos. You see exactly what it did before anything goes anywhere.

## When to apply

- Mother is asked for a bespoke data analysis on data the user can provide — "compute cohort LTV from this orders export and chart retention by acquisition channel."
- Mother is asked for a one-off script or transform — "dedupe this customer list and give me the cleaned file," "parse these logs and summarize the errors."
- The user wants a self-contained generated artifact that takes real computation — a chart, a computed dataset, a small script — rather than something the fixed MCP tool menu already expresses.
- The task is self-contained on uploaded inputs and a pre-baked toolchain — no network, no package installs, no repo or store access needed to do it.
- Refuse cleanly (do NOT open a sandbox) when the request needs something outside the US1 envelope — `pip`/`npm install`, cloning a repo, fetching a URL, or calling an external API. Say the capability arrives in a later release rather than spinning up a doomed sandbox or claiming partial success.
- Never present a coding result as done without running its checks; if there's no verifiable signal, surface it as proposed-but-unverified.

## Tools

| Tool | Description | Cost |
|------|-------------|------|
| `call_app_api` | Call a deployed app's own HTTP API so Mother can operate it (not just build it). Give app_id (from a deploy), the path (e.g. '/sources'), the method, and an optional JSON body. The base URL is resolved from the registry for THIS organization's app — you can only call your own apps, never an arbitrary URL. Returns the app's status code + response body. | Free |
| `code_build_app` | Emit the deploy manifest + versioned bundle for a blessed app-build sandbox. Pass session_id (from code_create_app_sandbox) and app_id; org is taken from auth. Omit version — modal auto-increments it. Returns manifest_s3_key (feed it to code_deploy_app), version, and a verification block (same shape as a generic session's terminate verification). Free; the deploy is billed at code_deploy_app. | Free |
| `code_create_app_sandbox` | Open the blessed Hono+D1 app-build sandbox for a registered app. Pass app_id (from register_app); org is taken from auth. fresh:true gives a clean scaffold (first build); fresh:false auto-restores the app's latest source into /workspace (an edit). Returns session_id (== sandbox_id) + created_at — drive it with the same code_upload/code_exec loop as a generic session, then call code_build_app to emit, then code_deploy_app. Free. | Free |
| `code_create_session` | **Platform-managed — the agent must not call this.** Open a Coding Agent sandbox session. The sandbox is created with block_network and zero secrets attached; one session caps at 600 seconds wall-clock (the modal-side self-kill). Pre-spend cap: refused if the org is at or over its daily sandbox-seconds cap (3600s/org/UTC-day). Free; sandbox-seconds are metered internally for the cap, not surfaced as a per-second billed rate. | Free |
| `code_deploy_app` | Deploy a built app (Worker + D1) from a typed deploy manifest in S3 to {app}.gentic.run. Pass manifest_s3_key (the manifest.json the sandbox build emitted) and optionally display_name (founder-facing; the subdomain slug is derived from it on first deploy). Pass app_id to redeploy an existing app (iteration — reuses the same slug/D1); omit it on the first deploy and one is minted + returned. The manifest is validated strictly and the deploy is refused unless the build proved egress was blocked. Cloudflare credentials never enter the sandbox. | 50¢ / call |
| `code_exec` | Run a shell command inside a Coding Agent sandbox session and get stdout/stderr/exit_code/elapsed_seconds back synchronously. A single exec is capped at 140s by gentic-modal's per-command soft timeout (session total caps at 600s). The session_id comes from code_create_session. Free. | Free |
| `code_get_diff` | Get the unified diff (+ a name-status file list) of all changes made in a Coding Agent sandbox session so far. Used by the agent loop to inspect mid-task progress. diff_text may be null if no changes have been made yet; files[] is always present. The session_id comes from code_create_session. Free. | Free |
| `code_list_apps` | List the apps your organization has deployed to {app}.gentic.run. Returns each app's app_id, display_name, live url, status, current_version_id (the version it's serving now — pass it back to resume editing that app), and last_deployed_at. Scoped to your organization; takes no arguments. Free. | Free |
| `code_terminate` | **Platform-managed — the agent must not call this.** Terminate a Coding Agent sandbox session. Returns elapsed_seconds_total (records to the per-org daily cap counter on every terminal path: success, cancel, timeout, crash) and the final artifact_uri assembled by gentic-modal. Pass created_at from the original code_create_session response — gentic-modal is stateless and computes elapsed from it. Free; sandbox-seconds recorded internally, not surfaced as a billed per-second rate. | Free |
| `code_upload` | Upload one or more files into a Coding Agent sandbox session. Each file is { path } plus exactly one of: content_b64 (inline base64, for small/moderate files <=10MB decoded) OR s3_key (a pre-staged S3 object key, for big files — bytes bypass the JSON gateway). The session_id comes from code_create_session. Free. | Free |
| `register_app` | Register a new Coding-Agent app and get its app_id BEFORE building it. Call this once at the start of a fresh app build, then pass the returned app_id through the build and to code_deploy_app. Optionally provide display_name (the founder-facing name; the subdomain slug is derived from it at first deploy). The per-org deployed-app cap is checked here. On a later edit of an existing app you already have the app_id — skip this and reuse it. Free. | Free |

> **Platform-managed tools** (`code_create_session`, `code_terminate`) are orchestrated by Mother's loop — the session is created and torn down for you. The agent must **never** call them directly; calling them errors. Use only `call_app_api`, `code_build_app`, `code_create_app_sandbox`, `code_deploy_app`, `code_exec`, `code_get_diff`, `code_list_apps`, `code_upload`, `register_app`. If a session tool appears unavailable, never simulate a result — report the actual error.

## Workflow

### 1. The session is opened for you (platform-managed)

Mother's loop calls `code_create_session` at the start of the activity — the agent does NOT. It opens an isolated sandbox with the network blocked and no secrets attached, and is refused up front if the org is at or over its daily sandbox-seconds cap (3600s/org/UTC-day), a pre-spend check so a capped org never burns compute it can't have. The `session_id` is threaded into the tools you do call; the sandbox lives provider-side and every call is keyed by it. Treat the session as already open — never call `code_create_session` yourself (it errors), and never simulate a result because a session looks unavailable.

### 2. Upload the inputs

Use `code_upload` to put the task's input files into the sandbox — each file is `{ path, content_b64 }`. This is how data gets in: US1 has no network egress, so the sandbox can't fetch anything itself. Upload the orders export, the customer list, the logs — whatever the task operates on — before running commands against them.

### 3. Run the work with code_exec

Run shell commands with `code_exec` against the pre-baked toolchain and get `stdout`/`stderr`/`exit_code`/`elapsed_seconds` back synchronously. A single command is capped at 140s (the session totals cap at 600s). Iterate: read the data, run the analysis, generate the artifact, write and run the checks. There are no installs or network calls — work with what's uploaded and what's already in the image.

### 4. Inspect progress with code_get_diff

`code_get_diff` returns the unified diff plus a name-status file list of everything changed in the session so far — use it to inspect mid-task progress and to assemble the reviewable artifact. `diff_text` may be null before any changes are made; the `files[]` list is always present.

### 5. Verify before done; termination is platform-managed

Before claiming done, run the task's checks in the sandbox with `code_exec`; only report success if they pass, otherwise surface the change as proposed-but-unverified. Termination is handled by Mother's loop, NOT the agent: `code_terminate` is called in a `finally` (passing `created_at` so the stateless modal side can compute elapsed, plus the `diff`, `files`, and `checks`), which tears the sandbox down promptly and records elapsed sandbox-seconds to the per-org daily cap on every terminal path — success, cancel, timeout, crash. The agent never calls `code_terminate` itself; it just produces the diff and the verification result for the loop to assemble into the artifact.

## Notes

- This is a Mother capability, not a connect-it-yourself MCP. The `code_*` tools are session-keyed and driven by Mother's own loop; a customer does not point their own agent at /code and call code_exec directly.
- Platform-managed tools: `code_create_session` and `code_terminate` are orchestrated by Mother's loop (session opened at activity start, terminated in a finally for metering + cancel safety). The agent must NEVER call them — it works only with `code_upload`, `code_exec`, and `code_get_diff`. Calling a platform-managed tool errors; if a session tool appears unavailable, report the actual error rather than simulating a result.
- US1 envelope: self-contained data and script tasks on uploaded inputs with a pre-baked toolchain and ZERO network egress. No `pip`/`npm install`, no repo clones, no URL fetches, no external API calls — a request that needs those is refused cleanly, not run into a failing sandbox.
- No access to your repositories or storefronts in this release — it operates only on Mother-owned compute and the inputs you provide. Storefront/repo fixes (US2) and building a product (US3) are later, separately-gated slices.
- Propose-only: a session returns a reviewable change-artifact (diff + files + verification result). Nothing is deployed, pushed, scheduled, or written back to your systems without explicit human approval.
- Isolation: each sandbox is created with the network fully blocked and no secrets attached, external to Mother's control plane — untrusted code never runs in the API/worker container, and one session can't reach another org's data.
- Bounded compute: 140s per command, 600s per session, and a 3600s/org/UTC-day cap checked before a sandbox is created; metering fires on every terminal path. Sandbox-seconds are metered internally for the cap — the tools themselves are free.
- Verify-before-done: a task's checks are run in the sandbox before a result is presented as complete; with no verifiable signal the change is surfaced as proposed-but-unverified rather than as success.

## Tool details

- `call_app_api` — Call a deployed app's own HTTP API so Mother can operate it (not just build it). Give app_id (from a deploy), the path (e.g. '/sources'), the method, and an optional JSON body. The base URL is resolved from the registry for THIS organization's app — you can only call your own apps, never an arbitrary URL. Returns the app's status code + response body.
  - `app_id` (string, required) — The app_id returned by code_deploy_app.
  - `path` (string, required) — Request path on the app, starting with '/' (e.g. '/sources', '/todos/1'). Host is NOT accepted — only the app's own subdomain is called.
  - `method` (string, enum: `GET` | `POST` | `PUT` | `PATCH` | `DELETE`, default: `"GET"`, required) — HTTP method. Defaults to GET.
  - `body` — Optional request body. An object is sent as JSON; a string is sent as-is. Ignored for GET/DELETE.
- `code_build_app` — Emit the deploy manifest + versioned bundle for a blessed app-build sandbox. Pass session_id (from code_create_app_sandbox) and app_id; org is taken from auth. Omit version — modal auto-increments it. Returns manifest_s3_key (feed it to code_deploy_app), version, and a verification block (same shape as a generic session's terminate verification). Free; the deploy is billed at code_deploy_app.
  - `session_id` (string, required) — The blessed sandbox to package — the session_id returned by code_create_app_sandbox.
  - `app_id` (string, required) — The app being built — the app_id from register_app. Must belong to the authenticated org.
  - `version` (integer) — Optional. Modal owns version numbering (auto-increments v{n+1}); pass it only if you are pinning a version, otherwise omit.
- `code_create_app_sandbox` — Open the blessed Hono+D1 app-build sandbox for a registered app. Pass app_id (from register_app); org is taken from auth. fresh:true gives a clean scaffold (first build); fresh:false auto-restores the app's latest source into /workspace (an edit). Returns session_id (== sandbox_id) + created_at — drive it with the same code_upload/code_exec loop as a generic session, then call code_build_app to emit, then code_deploy_app. Free.
  - `app_id` (string, required) — The app to build — the app_id returned by register_app. Must belong to the authenticated org.
  - `fresh` (boolean) — true (default) = clean blessed scaffold for a first build; false = modal auto-restores the app's latest source.tar.gz into /workspace for an edit.
- `code_create_session` _(platform-managed — orchestrated by Mother's loop; the agent must never call this directly)_ — Open a Coding Agent sandbox session. The sandbox is created with block_network and zero secrets attached; one session caps at 600 seconds wall-clock (the modal-side self-kill). Pre-spend cap: refused if the org is at or over its daily sandbox-seconds cap (3600s/org/UTC-day). Free; sandbox-seconds are metered internally for the cap, not surfaced as a per-second billed rate.
  - `task` (string, required) — Short human-readable description of what this session is for (logged for telemetry; not sent to a model).
- `code_deploy_app` — Deploy a built app (Worker + D1) from a typed deploy manifest in S3 to {app}.gentic.run. Pass manifest_s3_key (the manifest.json the sandbox build emitted) and optionally display_name (founder-facing; the subdomain slug is derived from it on first deploy). Pass app_id to redeploy an existing app (iteration — reuses the same slug/D1); omit it on the first deploy and one is minted + returned. The manifest is validated strictly and the deploy is refused unless the build proved egress was blocked. Cloudflare credentials never enter the sandbox.
  - `manifest_s3_key` (string, required) — S3 key of the deploy manifest.json (under orgs/{org_id}/...). The bundle key is read from inside the manifest.
  - `app_id` (string) — Existing app_id to redeploy (iteration). Omit on first deploy — a new app_id is minted and returned.
  - `display_name` (string) — Founder-facing app name. On first deploy a collision-safe subdomain slug is derived from it; ignored on redeploy. Defaults to the manifest app name.
- `code_exec` — Run a shell command inside a Coding Agent sandbox session and get stdout/stderr/exit_code/elapsed_seconds back synchronously. A single exec is capped at 140s by gentic-modal's per-command soft timeout (session total caps at 600s). The session_id comes from code_create_session. Free.
  - `session_id` (string, required) — The sandbox session_id returned by code_create_session.
  - `cmd` (required) — Command to run. Either a shell line or an argv array.
  - `timeout_seconds` (integer) — Per-exec timeout seconds (max 140 — gentic-modal's per-command soft cap; the modal tier clamps higher values down).
- `code_get_diff` — Get the unified diff (+ a name-status file list) of all changes made in a Coding Agent sandbox session so far. Used by the agent loop to inspect mid-task progress. diff_text may be null if no changes have been made yet; files[] is always present. The session_id comes from code_create_session. Free.
  - `session_id` (string, required) — The sandbox session_id returned by code_create_session.
- `code_list_apps` — List the apps your organization has deployed to {app}.gentic.run. Returns each app's app_id, display_name, live url, status, current_version_id (the version it's serving now — pass it back to resume editing that app), and last_deployed_at. Scoped to your organization; takes no arguments. Free.
- `code_terminate` _(platform-managed — orchestrated by Mother's loop; the agent must never call this directly)_ — Terminate a Coding Agent sandbox session. Returns elapsed_seconds_total (records to the per-org daily cap counter on every terminal path: success, cancel, timeout, crash) and the final artifact_uri assembled by gentic-modal. Pass created_at from the original code_create_session response — gentic-modal is stateless and computes elapsed from it. Free; sandbox-seconds recorded internally, not surfaced as a billed per-second rate.
  - `session_id` (string, required) — The sandbox session_id returned by code_create_session.
  - `created_at` (string, required) — The created_at timestamp from the code_create_session response. Required — gentic-modal uses it to compute elapsed_seconds_total.
  - `reason` (string, enum: `cancelled` | `timed_out` | `crashed`) — Caller-supplied reason for terminate when the activity knows it. Modal can't distinguish a TTL self-kill from a terminate() call, so the activity is the source of truth. Omit on success.
  - `diff` (string) — Optional final diff text the agent loop computed. Folded into the artifact bundle assembled at terminate.
  - `files` (array of object) — Optional final name-status list folded into the artifact bundle.
  - `checks` (array of object) — Optional verification check results (from the agent loop's verify-before-done step) folded into the artifact bundle.
- `code_upload` — Upload one or more files into a Coding Agent sandbox session. Each file is { path } plus exactly one of: content_b64 (inline base64, for small/moderate files <=10MB decoded) OR s3_key (a pre-staged S3 object key, for big files — bytes bypass the JSON gateway). The session_id comes from code_create_session. Free.
  - `session_id` (string, required) — The sandbox session_id returned by code_create_session.
  - `files` (array of object, required) — Files to upload. At least one. Each carries content_b64 OR s3_key.
- `register_app` — Register a new Coding-Agent app and get its app_id BEFORE building it. Call this once at the start of a fresh app build, then pass the returned app_id through the build and to code_deploy_app. Optionally provide display_name (the founder-facing name; the subdomain slug is derived from it at first deploy). The per-org deployed-app cap is checked here. On a later edit of an existing app you already have the app_id — skip this and reuse it. Free.
  - `display_name` (string) — Founder-facing app name. Stored now; used to derive the subdomain slug at first deploy. Can also be supplied to code_deploy_app instead.
  - `idempotency_key` (string) — Stable key (e.g. the build workflow id) so retried calls dedupe: the same key returns the same app_id and consumes no extra app-cap slot. Omit for a one-off registration.

---

_This SKILL.md is generated from the live Gentic MCP manifest. Tool names, descriptions, and pricing are always current. Gentic Code is a Mother capability: these tools are session-keyed and driven by Mother's own loop, not connected standalone. Learn more at https://gentic.co/code._