@cursor/july 0.1.101 → 0.1.103

package/docs/reference/hooks.md

@@ -5,56 +5,119 @@ description: "Observe-only subscribers to the session event stream: audit logs,
 
 # Hooks
 
-A hook is an observe-only subscriber to the session event stream. Hooks
-run after each event is recorded. They cannot change the event or the
-turn. That makes them the home for audit logging, metrics, mirroring
-transcripts into your own store, and maintaining derived state. Handler
-errors are logged and never fatal. A hook can't inject context into the
-next turn or block a turn.
-
-For deterministic context composition before the model runs, use the
-host path that already owns the wake: channel handlers (fetch, `callTool`,
-`workspaceFiles`, and the message you pass to `send`), plus
-`instructions.md`, skills, and `sandbox/workspace/` seed files. Hooks
-observe what happened; they do not assemble the prompt.
+A hook subscribes to the session event stream and runs a side effect
+after each event is recorded: an audit line, a metric, a copy of the
+transcript in your own store, or derived state for later turns. Hooks
+run in the serving process for every session of the agent, on local and
+cloud runtime turns alike.
+
+Hooks observe. They can't change the turn, the prompt, or the reply, and
+a handler that throws is logged and skipped. Treat the event as
+read-only; later subscribers see the same object. That makes hooks safe
+to add to a production agent, and the wrong tool for anything that must
+happen before the model runs or must fail a turn; see
+[When not to use a hook](#when-not-to-use-a-hook).
+
+`defineHook` is unrelated to
+[Cursor Agent hooks](https://cursor.com/docs/agent/hooks), the
+`.cursor/hooks.json` scripts that can observe, block, or modify the
+agent loop. Those still run inside a local session workspace.
+
+## Author a hook
 
 Author `agent/hooks/<name>.ts` with `defineHook` from
-`@cursor/july/hooks`:
+`@cursor/july/hooks`. This one meters tokens:
 
 ```ts
+// agent/hooks/usage.ts
 import { defineHook } from "@cursor/july/hooks";
 
 export default defineHook({
   events: {
     async "turn.completed"(event, ctx) {
-      const prior = await ctx.host.kv.get("last-result");
-      const notes = await ctx.host.files.read("notes.md");
-      console.log("turn done", ctx.session.id, event.data.usage, prior, notes);
+      if (ctx.session.purpose === "eval" || event.data.usage === undefined) {
+        return;
+      }
+      const { inputTokens, outputTokens } = event.data.usage;
+      ctx.host.otel.increment("acme.tokens.input", inputTokens);
+      ctx.host.otel.increment("acme.tokens.output", outputTokens);
     },
-    async "turn.failed"(event, ctx) {
-      // page, count, or record
+    async "turn.failed"(_event, ctx) {
+      ctx.host.otel.increment("acme.turn.failed", { channel: ctx.channel.id });
     },
   },
 });
 ```
 
-Keys are event types (see the
-[event vocabulary](./sessions.md#which-events-can-i-stream)), or `"*"`
-for everything. Handlers receive the event with its envelope (`index`,
-`sessionId`, `turnId?`, `at`) and a `HookContext`:
+Any module under `agent/hooks/`, subfolders included, is a hook named by
+its path without the extension: `agent/hooks/audit/usage.ts` is
+`audit/usage`. `*.test.ts` and `*.spec.ts` files are skipped. The
+default export must be `defineHook(...)`, names can't contain `__`, and
+an empty `events` map skips the hook with a warning; `agent-sdk validate`
+reports all three. An extension mounts its hooks as `<ns>__<name>`, and
+`disableHook()` removes one
+([Adjust a mounted extension](./extensions.md#adjust-a-mounted-extension)).
+
+`agent-sdk init` scaffolds `agent/hooks/memory.ts`, which exports
+`memoryHook()` from `@cursor/july/memory` and journals every turn for
+later sessions to read. Delete the file to opt out.
+
+## Events and payloads
+
+Keys are event types from the
+[event vocabulary](./sessions.md#which-events-can-i-stream), or `"*"`
+for every event. A typed key narrows `event.data`; a `"*"` handler
+receives the union, so switch on `event.type`. Every event carries the
+stream envelope `{ type, index, sessionId, turnId?, at, data }`, with
+`turnId` set on turn-scoped events.
+
+The payloads hooks read most often:
+
+| Event | `event.data` |
+| --- | --- |
+| `message.received` | `{ text }` |
+| `turn.completed` | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
+| `turn.failed` | `{ message }` |
+| `actions.requested` | `{ calls: [{ callId, toolName, args? }] }`. A call with `parentCallId` belongs to a subagent |
+| `action.result` | `{ callId, toolName, output?, isError, stubbed? }`. `stubbed` means a dry-run session answered a write without running it |
+
+The types are `SessionEvent`, `SessionEventType`, and `HookContext`,
+exported from `@cursor/july`.
+
+## Handler context
 
 | Member | What it is |
 | --- | --- |
-| `ctx.session` | Read-only session info: id, channel, mode, auth |
+| `ctx.session` | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title`, `sdkAgentId`, and `abs` when set |
 | `ctx.agent` | `{ name }` of the agent the event belongs to |
-| `ctx.channel` | `{ id, continuationToken }` for the owning channel |
-| `ctx.stateRoot` | The agent's durable state root. Prefer `ctx.host.kv` / `ctx.host.files` for derived state; this tree resets on hosted replace |
-| `ctx.host` | Shared host services; same as a tool's `ctx.host`. Pull JSON with `ctx.host.kv` and file-shaped state with `ctx.host.files` (session-bound by default; pass `{ scope: "deployment" }` for agent-wide files) |
-| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` auto-fills the session |
+| `ctx.channel` | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups |
+| `ctx.host.kv` | Durable JSON, shared by every session of the agent; the [storage backend](../storage.md#author-kv-ctx-host-kv) decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
+| `ctx.host.files` | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files |
+| `ctx.host.otel` | Counters, histograms, and tags, attributed to this session |
+| `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get |
+| `ctx.host.reminders` | Per-session [reminders](./schedules.md), the same API tools get |
+| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` fills in `sessionId` and `turnId` |
+| `ctx.stateRoot` | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files` |
+
+## When hooks run
+
+A hook runs after the event is durably recorded. It never delays the
+model turn and never sees an event that wasn't recorded.
+
+Within one session, events dispatch in order, one at a time: the
+channel's `events` handlers first, then each hook in discovery order.
+Sessions don't wait on each other.
 
-Hook context includes `ctx.host`, the same shared services a tool
-gets. Persist JSON with `ctx.host.kv` and file-shaped state with
-`ctx.host.files`. Hooks observe; they do not own delivery surfaces.
+Two consequences:
+
+- A slow handler holds up the next event's handlers for that session,
+  not the model. Keep handlers short and queue anything slow.
+- Hooks fire for eval sessions too. Check
+  `ctx.session.purpose === "eval"` before metering or paging.
+
+Each event reaches a hook at most once. A restart doesn't replay the log
+into hooks, so a mirror needs no dedupe, and the event log rather than
+the hook's copy is the source of truth.
 
 ## Hooks, channel events, evals, or A/B?
 
@@ -62,37 +125,143 @@ All of them consume the same stream, for different jobs:
 
 | | Hooks | Channel `events` | Evals | A/B (`defineAB`) |
 | --- | --- | --- | --- | --- |
-| Scope | every session on the agent | sessions the channel owns | one test turn | every live session; enrollment at creation, metrics on each turn |
-| Job | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface | assert: gates over the trajectory | `ab.assigned` + fold stream → `onSample` |
+| Scope | every session of the agent | sessions the channel owns | one test turn | every live session; enrollment at creation, metrics on each turn |
+| Job | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface | assert: gates over the trajectory | compare: sticky arms, then fold the stream into `onSample` metrics |
+| Context | `ctx.host`, `ctx.artifacts`, session info | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers | per-session samples in `onSample` |
 | Can affect the run | no | yes, it owns the surface | n/a | yes through arm instructions or `session.abs`; collection is observe-only |
 | Authored at | `agent/hooks/*.ts` | channel config | `evals/**/*.eval.ts` | [`agent/ab.ts` or `agent/ab/*.ts`](../ab.md) |
 
-For GitHub merge-box checks and sticky PR banners, use
-`githubChannel({ progress: { commitStatus, banner } })` from
-`@cursor/july/channels/github`. That is the supported Autofix-style
-path. See [GitHub: Show PR progress](../guides/github.md#show-pr-progress).
-Override channel `events` only when the lifecycle is custom, such as
-never-red status from tool output. Do not use `defineHook` for those
-writes.
+## When not to use a hook
+
+| You want to | Use instead |
+| --- | --- |
+| Add context before the model runs | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
+| Reply on Slack, comment on a PR, or post any other delivery | The channel's `events` map, or the Slack and GitHub packs |
+| Show PR progress (merge-box check, sticky banner) | `githubChannel({ progress: { commitStatus, banner } })`; see [Show PR progress](../guides/github.md#show-pr-progress) |
+| Block, approve, or rewrite a tool call | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool |
+| Act on the final assistant text, or fail a bad turn | [`defineResult`](./result.md) |
+| Gate a change on behavior | [Evals](../evals.md) |
+| Compare two prompts on live traffic | [`defineAB`](../ab.md) |
 
 ## Patterns
 
-Usage metering: subscribe to `turn.completed` and forward
-`event.data.usage` (token counts) to your metrics system.
+Usage metering is the [authoring example](#author-a-hook). Three more:
+
+### Alert on failure
+
+`turn.failed` carries the message, and `ctx.session.id` points at the
+trace. Skip interrupted turns; those are preemptions, not failures. Read
+secrets inside the handler: hosted deployments bind them after the
+process starts, so a module-scope read stays empty. Give the call a
+timeout, since a stalled request holds up later handlers on that
+session.
+
+```ts
+// agent/hooks/page-on-failure.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.failed"(event, ctx) {
+      const pagerUrl = process.env.PAGER_WEBHOOK_URL;
+      if (
+        pagerUrl === undefined ||
+        ctx.session.purpose === "eval" ||
+        event.data.message === "turn interrupted"
+      ) {
+        return;
+      }
+      await fetch(pagerUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          agent: ctx.agent.name,
+          session: ctx.session.id,
+          channel: ctx.channel.id,
+          message: event.data.message,
+        }),
+        signal: AbortSignal.timeout(5_000),
+      });
+    },
+  },
+});
+```
+
+### Mirror the transcript
+
+Subscribe to `"*"` and write one file per event, skipping the
+`*.appended` deltas: they arrive per token, and `message.completed`
+carries the final text. Session scope keeps transcripts apart without a
+session id in the path. The mirror holds reasoning text and raw tool
+arguments and outputs, so pick the store accordingly, and write to your
+own store instead when you need cross-session queries.
+
+```ts
+// agent/hooks/mirror.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "*"(event, ctx) {
+      if (event.type.endsWith(".appended")) {
+        return;
+      }
+      const name = String(event.index).padStart(6, "0");
+      await ctx.host.files.write(
+        `transcript/${name}.json`,
+        JSON.stringify(event)
+      );
+    },
+  },
+});
+```
+
+### Keep derived state across a replace
+
+Write it to `ctx.host.kv` under a session-prefixed key; a tool reads it
+back with `ctx.host.kv.get`.
+
+```ts
+// agent/hooks/last-result.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.completed"(event, ctx) {
+      await ctx.host.kv.put(`last-result/${ctx.session.id}`, {
+        at: event.at,
+        result: event.data.result ?? null,
+      });
+    },
+  },
+});
+```
+
+## Test and debug a hook
 
-Failure alerting: `turn.failed` carries the message, and
-`ctx.session.id` points at the trace.
+A hook definition is a plain object, so a unit test calls
+`hook.events["turn.completed"]` directly with an event and a stub
+`HookContext`. Discovery skips `*.test.ts`, so the test can live next to
+the hook.
 
-Derived state: persist ids that must survive hosted replace with
-`ctx.host.kv` or `ctx.host.files`. `stateRoot` resets on replace.
+At runtime:
 
-Transcript export: subscribe to `"*"` and append to your own store.
+- `agent-sdk validate --dir .` reports discovery errors and the
+  empty-handlers warning.
+- `agent-sdk info --dir . --json` lists the loaded hooks under
+  `agents[].hooks`.
+- Send a turn with `agent-sdk dev` or `agent-sdk run --dir . --message "…"`
+  and watch the serve log for
+  `hook "<name>" handler for <event> threw: …`. `run` prints that log on
+  stderr. On hosting, read it with [`agent-sdk logs`](./cli.md#logs).
 
 ## What's next
 
 Continue with these pages:
 
+- [Turn result](./result.md): fail a turn from `commit`, not from a hook
 - [Sessions and streaming](./sessions.md): the event vocabulary hooks observe
+- [Storage](../storage.md): where `ctx.host.kv` and `ctx.host.files` live
 - [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream
 - [Deployment](../deployment.md#observability): runtime logs and export

package/docs/reference/playground.md

@@ -32,6 +32,9 @@ Use the playground to chat, try channel routes, and inspect sessions.
   `/v1/dev/evals`). Schedule hand-dispatch still requires `--dev`.
 - **The surface**: inspect the discovered tools, skills, subagents, MCP
   connections, channels, and hooks.
+- **Custom tool chips**: drop `agent/playground/tools/<toolName>.tsx` to
+  change how that tool renders. Chips compile from the agent tree;
+  an [extension](./extensions.md) cannot contribute them.
 - **Raw events pane**: flip it on to inspect the event stream.
 - **Logs tab**: recent server log lines, polled from `GET /v1/logs`.
 - **A/Bs tab**: per-session and aggregate

package/docs/reference/project-layout.md

@@ -21,6 +21,8 @@ experiments can override their file-derived name.
 | `agent/host-connections/anytool.ts` | Host MCP connection `anytool` (host + `mcp oauth` only) |
 | `agent/skills/pr-review.md` | skill `pr-review` |
 | `agent/subagents/reviewer/` | subagent `reviewer` |
+| `agent/extensions/ci.ts` | extension mount `ci`; its contributions become `ci__<name>` |
+| `agent/extensions/notion.ts` | Cursor plugin mount `notion` (`cursorPlugin`); its skills, agents, and MCP servers become `notion__<name>` |
 | `agent/channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
 | `agent/ab.ts` | A/B experiment `ab` unless `name` overrides it |
 | `agent/ab/concise.ts` | A/B experiment `concise` unless `name` overrides it |
@@ -71,6 +73,7 @@ Each path maps to a capability and a reference page.
 | `agent/mcp-connections/<name>.ts` | MCP servers, available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`) | [MCP connections](./connections.md) |
 | `agent/host-connections/<name>.ts` | Privileged MCP servers for `ctx.host.mcp` and `mcp oauth`. The model never sees them. | [MCP connections](./connections.md) |
 | `agent/subagents/<id>/` | Child agent directory; `description` required | [Subagents](./subagents.md) |
+| `agent/extensions/<ns>.ts` or `agent/extensions/<ns>/` | A mounted extension or Cursor plugin; its contributions become `<ns>__<name>` | [Extensions](./extensions.md) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
 | `agent/otel.ts` | `defineOtel` OTLP export (traces, metrics, optional logs) | [OpenTelemetry](../guides/opentelemetry.md) |
@@ -78,6 +81,7 @@ Each path maps to a capability and a reference page.
 | `agent/ab.config.ts` | `defineABConfig` shared A/B settings | [Live A/B metrics](../ab.md) |
 | `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | [Storage](../storage.md) |
 | `agent/artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](./artifacts.md) |
+| `agent/result.ts` | `defineResult` host `commit` on the final assistant text | [Turn result](./result.md) |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](./schedules.md) |
 | `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](./sessions.md#what-goes-into-a-local-session-workspace) |
 | `agent/playground/` | Custom playground tool chips | [Playground](./playground.md) |

package/docs/reference/result.md

@@ -0,0 +1,94 @@
+---
+title: "Turn result"
+description: "Run host code on the final assistant text when a turn finishes. Throw to fail the turn."
+---
+
+# Turn result
+
+Judgment agents need a place to act on the model's last message: parse
+it, then page, comment, or close a ticket. Author `agent/result.ts`
+with `defineResult` from `@cursor/july/result`. When that file exists,
+every finished turn runs `commit` on the serving host with the full
+assistant text.
+
+A thrown `commit` fails the turn. Empty assistant text fails it too.
+Hooks still observe only; they cannot fail a valid turn.
+
+Use this for an end-of-turn actuation. Mid-turn actions belong in
+[tools](./tools.md). Durable records that outlive a session belong in
+[artifacts](./artifacts.md).
+
+## Author `agent/result.ts`
+
+```ts
+import { defineResult } from "@cursor/july/result";
+import { applyDecision, parseDecision } from "./lib/actuate.js";
+
+export default defineResult({
+  async commit(ctx) {
+    if (ctx.session.purpose === "eval") {
+      return;
+    }
+    await applyDecision(parseDecision(ctx.text), ctx.host);
+  },
+});
+```
+
+`commit` is required. Parse `ctx.text` however the agent needs. Tell
+the model the document shape in `instructions.md`. The Agent SDK does
+not inject a schema.
+
+Put `result.ts` on the root agent only. A copy under a subagent is
+ignored with a warning.
+
+## Commit on the host
+
+`commit` runs in the serving process after the model finishes, before
+the turn completes. `ctx` is the same host surface a server tool gets,
+plus the turn text:
+
+| Member | What it is |
+| --- | --- |
+| `ctx.session` | The session that produced this turn, including `purpose` |
+| `ctx.host` | Shared host services (`kv`, `files`, `mcp`) |
+| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade |
+| `ctx.stateRoot` | The agent's durable state root |
+| `ctx.workspaceDir` | The session workspace |
+| `ctx.text` | The full assistant string |
+
+A dry-run session skips `commit` and still completes. Eval sessions do
+run `commit`; return early when `ctx.session.purpose === "eval"` if the
+handler must not actuate.
+
+On cloud runtime, the model still runs on the VM. `commit` runs on the
+serving host after the turn returns.
+
+`GET /v1/info` reports `result: true` when the file is authored.
+
+## Assert in evals
+
+`t.succeeded()` fails when `commit` throws or the turn produced no
+text, because those are turn failures. Read the document on `t.reply`.
+
+```ts
+import { defineEval, includes } from "@cursor/july/evals";
+
+export default defineEval({
+  async test(t) {
+    await t.send("Triage LIN-1842. It duplicates LIN-1801.");
+    t.succeeded();
+    t.check(t.reply, includes("duplicate"));
+  },
+});
+```
+
+## What's next
+
+Continue with these pages:
+
+- [Evals](../evals.md): `t.succeeded` and `t.reply`
+- [Sessions and streaming](./sessions.md): `turn.completed` and
+  `turn.failed`
+- [Hooks](./hooks.md): observe the stream after the turn has already
+  settled
+- [Project layout](./project-layout.md): where `agent/result.ts` lives

package/docs/reference/sessions.md

@@ -94,7 +94,9 @@ within one session. The `at` field is an ISO-8601 timestamp.
 
 Pair `actions.requested` with `action.result` to reconstruct the tool
 trajectory. Read `turn.completed.data.usage` for input, output, and
-cache token counts.
+cache token counts. When `agent/result.ts` is authored, a thrown
+`commit` or empty assistant text emits `turn.failed` instead of
+`turn.completed`. See [Turn result](./result.md).
 
 ## How do I stream or replay session events?
 

package/docs/reference/skills.md

@@ -85,4 +85,6 @@ Continue with these pages:
 
 - [Instructions](./instructions.md): what stays always-on
 - [Tools](./tools.md): when prose needs to become code
+- [Extensions](./extensions.md): skills installed as a package under a
+  namespace
 - [Project layout](./project-layout.md): where skills sit in the tree

package/docs/reference/tools.md

@@ -19,8 +19,7 @@ access to `process.env` and your `agent/lib/` code. Local turns call
 server tools as SDK custom tools. Cloud turns reach them over
 authenticated HTTP MCP back to the serve host when `--public-url` or
 `--cloud-tools-url` is set; without either, the server warns at startup
-and cloud turns omit them (see
-[Cloud runtime](../guides/cloud-runtime.md#what-changes-on-cloud)).
+and cloud turns omit them.
 
 ```ts
 // agent/tools/inspect_pr.ts
@@ -343,4 +342,6 @@ Continue with these pages:
   lifecycle in full
 - [MCP connections](./connections.md): tools that come from MCP servers
   instead
+- [Extensions](./extensions.md): tools installed as a package under a
+  namespace
 - [Evals](../evals.md): gating tool decisions with `calledTool`

package/docs/templates/pr-autofixer.md

@@ -123,6 +123,3 @@ agent-sdk deploy
 Run it from the agent's git checkout. It infers repository, ref, path,
 and slug, builds on Cursor-managed hosting, and prints the URL.
 `agent-sdk deployments` shows status.
-
-See [Cloud runtime](../guides/cloud-runtime.md) for what changes on
-the VM.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.101",
+  "version": "0.1.103",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -13,11 +13,7 @@
   "module": "dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "july": "./dist/bin/agent-serve.js",
-    "agent-sdk": "./dist/bin/agent-serve.js",
-    "agentsdk": "./dist/bin/agent-serve.js",
-    "agentkit": "./dist/bin/agent-serve.js",
-    "agent-serve": "./dist/bin/agent-serve.js"
+    "agent-sdk": "./dist/bin/agent-serve.js"
   },
   "publishConfig": {
     "access": "public"
@@ -26,9 +22,17 @@
     "dist/**/*",
     "!dist/playground-central/**",
     "!dist/internal/tenant-mcp/**",
+    "!dist/internal/grokbot/**",
+    "!dist/internal/review-comments.*",
+    "!dist/internal/shallow-clone.*",
+    "!dist/internal/managed-delivery.*",
     "src/**/*",
     "!src/**/*.test.ts",
     "!src/internal/tenant-mcp/**",
+    "!src/internal/grokbot/**",
+    "!src/internal/review-comments.ts",
+    "!src/internal/shallow-clone.ts",
+    "!src/internal/managed-delivery.ts",
     "skills/**/*",
     "templates/**/*",
     "docs/**/*.md",
@@ -83,6 +87,18 @@
       "import": "./dist/channels/origin/index.js",
       "default": "./dist/channels/origin/index.js"
     },
+    "./channels/gitlab": {
+      "anysphere-source": "./src/channels/gitlab/index.ts",
+      "types": "./dist/channels/gitlab/index.d.ts",
+      "import": "./dist/channels/gitlab/index.js",
+      "default": "./dist/channels/gitlab/index.js"
+    },
+    "./channels/bitbucket": {
+      "anysphere-source": "./src/channels/bitbucket/index.ts",
+      "types": "./dist/channels/bitbucket/index.d.ts",
+      "import": "./dist/channels/bitbucket/index.js",
+      "default": "./dist/channels/bitbucket/index.js"
+    },
     "./channels/deployments": {
       "anysphere-source": "./src/channels/deployments/index.ts",
       "types": "./dist/channels/deployments/index.d.ts",
@@ -182,6 +198,13 @@
       "import": "./dist/artifacts.js",
       "default": "./dist/artifacts.js"
     },
+    "./result": {
+      "anysphere-source": "./src/result.ts",
+      "bun": "./dist/result.js",
+      "types": "./dist/result.d.ts",
+      "import": "./dist/result.js",
+      "default": "./dist/result.js"
+    },
     "./kv": {
       "anysphere-source": "./src/kv.ts",
       "bun": "./dist/kv.js",
@@ -289,21 +312,17 @@
   "devDependencies": {
     "@anysphere/agent-store-sync": "workspace:*",
     "@anysphere/ui": "workspace:*",
-    "@base-ui/react": "1.6.0",
-    "@stylexjs/stylex": "0.18.3",
     "@stylexswc/rs-compiler": "^0.18.0",
     "@tanstack/react-virtual": "3.13.23",
     "@types/js-yaml": "4.0.9",
     "@types/ms": "^2.1.0",
     "@types/node": "catalog:",
-    "@types/pg": "^8.16.0",
     "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@typescript/native-preview": "7.0.0-dev.20260701.1",
     "@vitejs/plugin-react": "^5.1.2",
     "minimatch": "^10.2.5",
-    "pg": "^8.18.0",
     "pretty-ms": "^9.2.0",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",

package/skills/framework-map/SKILL.md

@@ -44,8 +44,11 @@ Path is identity. Full list: README "Folder structure".
 | `agent/mcp-connections/<name>.ts` | MCP. Never name an account file `cursor.ts`. `advertiseTools: true` for named local tools |
 | `agent/host-connections/<name>.ts` | Privileged MCP for `ctx.host.mcp` / `mcp oauth` |
 | `agent/subagents/<id>/` | Child agent (`description` required) |
+| `agent/extensions/<ns>.ts` | Mounted extension or Cursor plugin (`cursorPlugin`); contributions are `<ns>__<name>` |
 | `agent/channels/*.ts` | Slack / GitHub / custom HTTP |
 | `agent/hooks/*.ts` | Observe-only |
+| `agent/artifacts.ts` | Durable tagged outputs (`defineArtifacts`) |
+| `agent/result.ts` | Host `commit` on the final assistant text (`defineResult`) |
 | `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |
 | `agent/otel.ts` | OpenTelemetry (`defineOtel`) |
 | `agent/schedules/*` | Cron. Never auto-fire under `--dev` |

package/skills/otel/SKILL.md

@@ -33,9 +33,13 @@ export default defineOtel({
 3. `serve(dir, { otel: { … } })`. `otel: false` disables env and
    authored config.
 
+Hosted v2 secrets arrive after bake. Use `defineOtel(() => …)` so flush
+re-resolves exporters. Authored `agent/otel.ts` records from process
+start even when the factory returns no exporters yet.
+
 | Signal | Default |
 | --- | --- |
-| Traces | on (`agent_sdk.http` → session → turn → tool / subagent) |
+| Traces | on (`agent_sdk.http`; `agent_sdk.turn` → tool / subagent) |
 | Metrics | on (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`) |
 | Logs | off (`logs: true` or `OTEL_LOGS_EXPORTER=otlp`) |
 
@@ -51,5 +55,6 @@ ctx.host.otel.record("abc.approval.duration_ms", 1420);
 ```
 
 Prefix names with team or agent. No custom spans. Join on
-`cursor.conversation.id` and `agent_sdk.agent`. Run `serve` as its
-own process when Agent SDK should own the destination.
+`agent_sdk.session_id` / `cursor.conversation.id` and
+`agent_sdk.agent`. Run `serve` as its own process when Agent SDK
+should own the destination.

package/src/ab.ts

@@ -6,7 +6,7 @@
  * `ab.assigned` events; arms are exposed on {@link SessionInfo.abs} for the
  * agent loop (tools / optional per-variant `instructions`). {@link ABCollector}
  * folds the event stream into metrics and calls {@link ABConfig.onSample}.
- * There is no `agent-serve ab` test runner.
+ * There is no `agent-sdk ab` test runner.
  *
  * Assignments and foldable metrics live in each session's `events.ndjson`
  * (survive serve restart). Optional project defaults in `agent/ab.config.ts`