refactor(api)!: prune internals and unify built-in grep

.changeset/prune-authoring-surface.md

@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Remove loader-only guards, event framing exports, deprecated code-extension GitHub/computer-use aliases, and legacy audience auth fields. Built-in and code-extension grep now share bounded modes and workspace containment; import named callback/config types from their authoring entries.

docs/channels/custom.mdx

@@ -501,15 +501,7 @@ export default defineChannel({
 
 The input contains the channel's `state`, `caller`, `channel`, and `environment`. A principal caller omits `principalId`, `issuer`, and `subject`, but its `attributes` come from route auth and can still contain identifying values. Return `"public"`, `"private"`, or `"unknown"`. Return `"unknown"` when the channel does not have enough evidence to classify confidently; consumers treat it as non-public. A missing, throwing, asynchronous, or malformed classifier also fails closed to `"unknown"`. A `metadata()` projection's `audience` field does not classify visibility; use `audience(input)`.
 
-When you explicitly annotate a callback, use `AudienceContext<TState>`. `AudienceInput<TState>` remains supported for existing callbacks while you migrate.
-
-Existing callbacks can continue using `auth?.principalType` while you migrate:
-
-```ts
-audience({ auth }) {
-  return auth?.principalType === "user" ? "private" : "unknown";
-}
-```
+When you explicitly annotate a callback, use `AudienceContext<TState>`. The retired `AudienceInput`, `AudiencePrincipal`, and `auth` input are not supported; classify the privacy-limited `caller` instead.
 
 Classification is fixed when the session is created. Continuation turns from a different caller do not reclassify an existing session. When a parent dispatches a local subagent, the child inherits the parent's audience while the framework forwards the parent's custom channel metadata separately.
 

docs/code-extension.mdx

@@ -92,11 +92,11 @@ export default git({});
 
 Configure `github` to broker GitHub access through Connect instead. The extension then adds the authenticated `git__gh` tool, tells the agent to use it for every authenticated GitHub operation, and switches `git__pr` to `gh-signed-commit` for repositories that require verified signatures.
 
-| Option             | Required      | Effect                                                                                     |
-| ------------------ | ------------- | ------------------------------------------------------------------------------------------ |
-| `github.connector` | With `github` | Connector that mints a GitHub token                                                        |
-| `github.org`       | With `github` | Organization whose repositories the `gh` tool can access                                   |
-| `github.broker`    | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules |
+| Option             | Required      | Effect                                                                                            |
+| ------------------ | ------------- | ------------------------------------------------------------------------------------------------- |
+| `github.connector` | With `github` | Connector that mints a GitHub token                                                               |
+| `github.org`       | With `github` | Organization whose repositories the `gh` tool can access                                          |
+| `github.broker`    | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules        |
 | `github.authorize` | No            | `authorize({ auth, repository, token })` callback that allows or denies each `gh` tool invocation |
 
 The `gh` tool requests a token scoped to exactly one repository in `github.org` for each invocation. The sandbox process receives a placeholder `GH_TOKEN`, and the firewall exchanges it on matching GitHub requests. Your `github.broker` callback receives the header-transform rules for the command, then `null` to remove the lease. The callback must preserve your other network rules. GitHub authentication has no command-delivery option.
@@ -130,7 +130,7 @@ export default git({
 
 ### Migrate from `code({ github })`
 
-`code({ github })` is deprecated. While it is set, the code extension still contributes `code__gh`, its GitHub instructions, and the signed-commit `code__pr` skill. Without it, the code extension contributes no GitHub tool, instructions, or pull request skill. Move the `github` option to `git({ github })`, and import `gh` and the GitHub sandbox helpers from `eve/extensions/git/tools` and `eve/extensions/git/sandbox`.
+`code({ github })` is rejected. Move the `github` option to `git({ github })`, and import `gh` and the GitHub sandbox helpers from `eve/extensions/git/tools` and `eve/extensions/git/sandbox`.
 
 ## Prepare the sandbox
 

docs/concepts/built-in-tools.md

@@ -382,7 +382,8 @@ Remove the file to remove the tool. `disableTool()` is unnecessary because `glob
 
 ### `grep`
 
-`grep` searches sandbox file contents with a regular expression. Add it:
+`grep` searches files inside the sandbox workspace. It is also the implementation of the code
+extension's `code__grep` tool. Add it:
 
 ```sh
 eve add tool/grep
@@ -406,6 +407,16 @@ export default defineTool({
 
 Remove the file to remove the tool. `disableTool()` is unnecessary because `grep` is not added by default.
 
+Inputs are `pattern`, optional `path`, `glob`, `ignoreCase`, `literal`, `context`, `limit`, and
+`outputMode`. `files_with_matches` is the default and lists paths; `content` returns matching
+lines and `count` returns per-file totals. Identifier-like patterns use literal matching unless
+`literal: false` is explicit. The default limit is 50 rows, capped at 200, with additional byte
+and line bounds. Relative paths resolve inside the workspace; parent traversal and symlinks
+outside it are rejected. Ripgrep respects `.gitignore`; the POSIX fallback does not.
+
+Results contain `content`, `matchCount`, `outputMode`, `path`, and `truncated`. Use
+`outputMode: "content"` when migrating a caller that previously expected matching lines.
+
 ### `no_reply`
 
 `no_reply` ends the turn without a reply. Use it when a scheduled check finds nothing to report, or when an action the agent already took is the whole answer. The model calls it with an optional `{ reason }`, which stays in the session history and traces and is never sent. The turn completes without a final message, so channels and schedule sends post nothing, and later turns see that the agent chose to stay quiet. Add it:

docs/concepts/upgrade-to-v27-events.md

@@ -312,6 +312,21 @@ Reusable eve config callbacks can use `WithEveConfigFunction` and `WithEveConfig
 `eve/workflow-modules` now declares only the authored workflow helpers documented by eve,
 not the entire vendored Workflow SDK.
 
+## Retired aliases and internal helpers
+
+Mount `eve/extensions/git` with `github` settings instead of `code({ github })`, and import
+computer-use tools from their own extension. `eve/models/openai` exports `chatgpt`, not
+`experimental_chatgpt`. `defineExtension` takes only its options, not a namespace argument.
+
+Audience callbacks take `AudienceContext` and its privacy-limited `caller`; `auth`,
+`AudienceInput`, and `AudiencePrincipal` are removed. Event framing records and loader-only
+guards are not public authoring APIs. `JsonValue`, `JsonObject`, `JsonArray`, and `JsonPrimitive`
+have one public home, `eve/events`.
+
+`grep` and `code__grep` now share the code extension's modes, bounded output, and workspace
+containment. The default output lists matching files; pass `outputMode: "content"` to retain
+line output. `limit` bounds returned rows (50 by default, maximum 200), not matches per file.
+
 ## Clients and frontends
 
 - **Frontend commands resolve on acceptance.** `EveAgentStore.send()` and the frontend hooks'

docs/reference/typescript-api.md

@@ -145,7 +145,7 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 | `eve/instrumentation/otel`                                                        | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types                                              |
 | `eve/local-dev`                                                                   | `getLocalDevCapability`, `LocalDevCapability`                                                                                  |
 | [`eve/models`](../guides/decide)                                                  | Automatic model selection with `auto`                                                                                          |
-| `eve/models/openai`                                                               | `openai`, `chatgpt`, deprecated `experimental_chatgpt`                                                                         |
+| `eve/models/openai`                                                               | `openai`, `chatgpt`                                                                                                            |
 | `eve/models/anthropic`                                                            | `anthropic`                                                                                                                    |
 | [`eve/ai`](../guides/decide#decide-inside-a-tool)                                 | Standalone `decide`                                                                                                            |
 | `eve/evals`                                                                       | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                                                                      |
@@ -182,7 +182,7 @@ export default defineAgent({
 });
 ```
 
-Pass another bare OpenAI model slug to override the default. `experimental_chatgpt()` remains as a deprecated alias.
+Pass another bare OpenAI model slug to override the default. The retired `experimental_chatgpt` alias is not exported.
 
 `chatgpt()` uses stateless requests (`store: false`). eve retains reasoning summaries and encrypted reasoning in session history and replays them after tool calls and on later turns. You do not need to configure `reasoning.encrypted_content` explicitly.
 

e2e/fixtures/agent-tools-sandbox/evals/sandbox/file-tools.eval.ts

@@ -14,7 +14,7 @@ export default defineEval({
     await t.send(
       [
         `Use the write_file tool to create the file ${FILE_TOOLS_PATH} with exactly this content: ${FILE_TOOLS_TOKEN}`,
-        `Then use the grep tool to search for ${FILE_TOOLS_TOKEN} under /workspace.`,
+        `Then use the grep tool to search for ${FILE_TOOLS_TOKEN} under /workspace with outputMode content.`,
         "Reply with the matching line verbatim.",
       ].join("\n"),
     );

packages/eve-code/AGENTS.md

@@ -7,13 +7,13 @@ Before writing code, read the installed eve package docs for extensions, hooks,
 ## Boundaries
 
 - Connector UIDs enter through extension config. The authentication hook resolves Vercel app tokens before each turn.
-- GitHub instructions, the `pr` skill, and the `gh` tool belong to `@eve/git` (`eve/extensions/git`). The deprecated `github` config keeps `code__gh`, `code__pr`, and the GitHub instructions through `extension/lib/github-compat.ts`, which imports `eve/extensions/git/sandbox`; add no other GitHub or pull request content here.
+- GitHub instructions, the `pr` skill, and the `gh` tool belong to `@eve/git` (`eve/extensions/git`). The removed `github` config is rejected; do not add GitHub or pull request contributions here.
 - Consumers with non-Connect credentials may call `authenticateGitHub` or `authenticateVercel` directly from their sandbox lifecycle.
 - Broker credentials without placing them in model-authored URLs or arguments.
 - Use real `git`, `gh`, and `vc` CLIs rather than bespoke repository lifecycle tools.
 - Keep `apply_patch` as the only extension-owned file editing primitive.
 - Keep shared implementation under `extension/lib/`; filesystem paths define contribution names.
-- Computer use lives in `@eve/computer-use` (`eve/computer-use`). Keep the deprecated computer-use re-exports in `extension/lib/sandbox.ts` until they are removed; do not add computer-use code here.
+- Computer use lives in `@eve/computer-use` (`eve/computer-use`). Import its public helpers directly; do not add computer-use code or re-exports here.
 
 ## Build and publish
 

packages/eve-code/README.md

@@ -6,8 +6,7 @@ It ships inside the `eve` package. This private `@eve/code` workspace package is
 
 - `eve/extensions/code`: the extension
 - `eve/extensions/code/sandbox`: sandbox bootstrap and credential helpers
-- `eve/extensions/code/tools`: `apply_patch` and `grep` (`gh` is a deprecated re-export)
-- `eve/extensions/code/prwatch`: PR-watch primitives for consumer-owned workflow tools
+- `eve/extensions/code/tools`: `apply_patch` and `grep`
 
 ## Mount
 
@@ -21,9 +20,9 @@ export default code({
 });
 ```
 
-Both connectors are optional; `code({})` mounts without either. The Vercel connector requests an app-subject token. Firewall delivery is the default and keeps tokens outside sandbox processes; without a consumer `broker`, it requires a sandbox provider that exposes `setNetworkPolicy()` and fails otherwise. Use `delivery: "command"` on the Vercel connector for providers without mutable network policy. A top-level `broker(sandbox, rules)` callback lets the consumer merge Vercel credential rules into its own network policy.
+The Vercel connector is optional; `code({})` mounts without it. The Vercel connector requests an app-subject token. Firewall delivery is the default and keeps tokens outside sandbox processes; without a consumer `broker`, it requires a sandbox provider that exposes `setNetworkPolicy()` and fails otherwise. Use `delivery: "command"` on the Vercel connector for providers without mutable network policy. A top-level `broker(sandbox, rules)` callback lets the consumer merge Vercel credential rules into its own network policy.
 
-The `github` option is deprecated; configure it on `eve/extensions/git` instead. While it is set here, this extension still contributes `code__gh`, its GitHub instructions, and the signed-commit `code__pr` skill. Without it, this extension contributes no GitHub tool, instructions, or pull request skill.
+The retired `github` option is rejected. Configure `eve/extensions/git` for GitHub tools, instructions, and the pull request skill.
 
 The read-only worker subagent defaults to `openai/gpt-5.6-terra-fast` with `xhigh` reasoning. Set `worker: { model, reasoning, openaiReasoningEffort? }` to choose another model; `openaiReasoningEffort` is passed to OpenAI models as `reasoningEffort`.
 
@@ -48,7 +47,7 @@ export default defineSandbox(() => environment.open());
 
 eve derives the prepared environment generation from the sandbox file and environment options, not from imported helpers, so upgrading eve alone does not rebuild an existing prepared artifact.
 
-Computer use lives in `eve/computer-use`. Mount it next to this extension when the sandbox has a desktop. `installComputerUse`, `startComputerUse`, and `COMPUTER_USE_REVALIDATION_KEY` are still re-exported from `eve/extensions/code/sandbox`, and `computer_use` from `eve/extensions/code/tools`, but both are deprecated.
+Computer use lives in its own extension. Import its tools and sandbox helpers directly; the deprecated code re-exports are removed.
 
 Preparation ensures `gh`, installs wrappers for `gh`, `vc`, and `gh-signed-commit`, and installs TypeScript diagnostics. With `eve/extensions/git` configured for `github`, repositories requiring verified signatures use `gh-signed-commit` through its `gh` tool.
 

packages/eve-code/extension/extension.ts

@@ -2,49 +2,33 @@ import { defineExtension } from "eve/extension";
 import type { SandboxSession } from "eve/sandbox";
 import { z } from "zod";
 
-import type { GitHubConfig } from "eve/extensions/git/sandbox";
-
 export type CredentialPolicyBroker = (
   sandbox: SandboxSession,
   rules: Record<string, Record<string, string>>,
 ) => Promise<void>;
 
-export type { GitHubLeaseRule } from "eve/extensions/git/sandbox";
-
-export type GitHubLeaseBroker = GitHubConfig["broker"];
-
 const fn = <T>() => z.custom<T>((value) => typeof value === "function");
 const delivery = z.enum(["firewall", "command"]).default("firewall");
 const reasoning = z.enum(["provider-default", "none", "minimal", "low", "medium", "high", "xhigh"]);
 const openaiReasoningEffort = z.enum(["none", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
 export default defineExtension({
-  config: z.object({
-    /**
-     * @deprecated Mount `eve/extensions/git` with this `github` config instead.
-     * While set, this extension still contributes the authenticated `gh` tool,
-     * its instructions, and the signed-commit `pr` skill.
-     */
-    github: z
-      .object({
-        connector: z.string().min(1),
-        org: z.string().min(1),
-        broker: fn<GitHubLeaseBroker>(),
-      })
-      .optional(),
-    vercel: z
-      .object({
-        connector: z.string().min(1),
-        delivery,
-      })
-      .optional(),
-    broker: fn<CredentialPolicyBroker>().optional(),
-    worker: z
-      .object({
-        model: z.string().min(1),
-        reasoning,
-        openaiReasoningEffort: openaiReasoningEffort.optional(),
-      })
-      .optional(),
-  }),
+  config: z
+    .object({
+      vercel: z
+        .object({
+          connector: z.string().min(1),
+          delivery,
+        })
+        .optional(),
+      broker: fn<CredentialPolicyBroker>().optional(),
+      worker: z
+        .object({
+          model: z.string().min(1),
+          reasoning,
+          openaiReasoningEffort: openaiReasoningEffort.optional(),
+        })
+        .optional(),
+    })
+    .strict(),
 });