@vantageos/agent-engine 0.1.0-alpha.6 → 0.1.0-alpha.8

package/README.md

@@ -1,424 +1,41 @@
 # @vantageos/agent-engine
 
-Reusable Convex component (pattern `@convex-dev/*`, house precedent
-`vantage-doc-forge`): durable agent engine. **An agent is a DATA
-AGGREGATE** — root sheet + child tables (skills, recursive subagents,
-connections, habits, sandbox config, per-tool approvals) — **never compiled
-code**. Instant creation, zero deployment. Built on `@convex-dev/workflow`
-+ `@convex-dev/workpool` (+ `@convex-dev/agent` for threads/context).
-
-Consumers, in order: VantagePeers (Sigma, I1 long-task survival),
-EveVantage (Hestia), VantageCRM (Theta).
-
-Bible: `elpiarthera/ElPi-Corp` (private) pinned @ `60b69bfc` —
-`analysis/evevantage/SYNTHESE.md` §4/§7,
-`analysis/evevantage/i0-research-convex-components.md`,
-`analysis/evevantage/mvp-evevantage.md` §2. Upstream reference:
-https://github.com/vercel/eve (reasoning source, never an opaque
-dependency).
-
-## EVE PARITY BY DESIGN
-
-Non-negotiable rule (SYNTHESE §4.e-ter): slots, contracts and vocabulary
-mirror `vercel/eve`. Every deliberate divergence is marked **"notre
-ligne"** below, in this table and in the code comments next to the field.
-
-| Eve slot / concept | Source (vercel/eve) | Our table / contract | Notes |
-|---|---|---|---|
-| Authored agent = a folder, `compileAgent` | `packages/eve/src/compiler/compile-from-memory.ts:86-87` | `agents` root row | **notre ligne** — we never compile; the row IS the agent |
-| `name` derived from folder path (no `name` field) | `agent-definition.ts:281-284` | `agents.name` | **notre ligne** — required field, since we have no folder |
-| `description` | `agent-definition.ts:291` | `agents.description` | direct parity |
-| `instructions` (`instructions.md`) | `shared/instructions-definition.ts:1-18` | `agents.instructions` | direct parity |
-| `model` (required) | `agent-definition.ts:304` | `agents.model` | direct parity |
-| reasoning effort | `agent-definition.ts:315-319` | `agents.reasoningEffort` | direct parity |
-| model provider / API key | not in the Eve repo (env-only) | `agents.modelProvider` + `modelKeys` table | **notre ligne** — BYOK (mvp §2.3), server-only table split from `agents` so list/get can never leak the key |
-| `limits.maxSubagents`, `maxInputTokensPerSession` | `agent-definition.ts:163-207` | `agents.maxSubagents`, `agents.maxInputTokensPerSession` | direct parity |
-| `dynamicSkills` / skills | `manifest.ts:722-725`, `agent-definition.ts:139` | `skills` child table | direct parity |
-| `dynamicTools` / tools | `manifest.ts:722-725` | resolved at read-time from `connections` + `toolApprovals` | direct parity |
-| Tool `approval: Approval<...>` (`always`/`once`/`never`) | `public/definitions/tool.ts:117-125` | `toolApprovals` child table | direct parity |
-| MCP/OpenAPI connections (`defineMcpClientConnection`) | `public/definitions/connections/mcp.ts:23-48` | `connections` child table | direct parity. Our VantagePeers tools (memory, tasks, messages, notes) are wired here as an MCP connection, on by default — **notre ligne**, mvp §2.2 |
-| Declared subagents (named tool, strict isolation) | https://eve.dev/docs/subagents ("a declared subagent inherits nothing from the root's authored slots") | `subagents` child table (`parentAgentId` -> `childAgentId`, recursive) + `engine/delegation.declareSubagent` / `listSubagents` (I6) | direct parity. Isolation is by construction: `declareSubagent` writes ONLY the link + `toolName`; the child's own slots are only ever read through `engine/resolvers.resolveManifest` against a session on `childAgentId` — never copied onto the parent (proven: `engineDelegation.test.ts`, "manifest carries ONLY its own skills") |
-| Subagent tool-name collision -> **build rejected** | https://eve.dev/docs/subagents ("eve rejects the build rather than picking a winner") | `engine/delegation.declareSubagent`'s build-time collision guard (`by_org_parent_tool` index + reserved `"agent"` name + `toolApprovals` lookup) | direct parity — a colliding `declareSubagent` call throws and writes nothing, never picks a silent winner |
-| Built-in `agent` tool — clone of the root, root-only, **NOT recursive** | https://eve.dev/docs/subagents | `engine/delegation.invokeAgentClone`, `agentCloneRuns` child table, `viaAgentTool` recursion guard | direct parity — a clone invocation cannot invoke the `agent` tool again; refused before any row is written or the wake-up pool is touched |
-| Inter-agent delegation mechanism | not modeled explicitly in `vercel/eve`'s own docs | `engine/delegation.delegateToSubagent` / `invokeAgentClone`, BOTH terminate in the SAME public `engine.wakeup.enqueue` (T4/I2) — one pause/wake system, not two (SYNTHESE §4.d) | **notre ligne (mechanism)** — delegation IS a wake-up: A parks on `step.awaitEvent`, B's work is enqueued through `wakeupPool`, `onComplete` -> `sendEvent` wakes A. No second `onComplete`/`sendEvent` path exists anywhere in this engine |
-| `sandbox` | `agent-definition.ts:150-160` | `sandboxConfig` child table (Vercel Sandbox, egress policy, allowlist) | direct parity, I0 §8 |
-| `schedules` / hooks -> "habits" | `manifest.ts:143`, `:726` | `habits` + `habitRuns` child tables (dynamic cron per agent/org, `@convex-dev/crons`, see "Mandates & habits (T4)" below) | **notre ligne (naming + mechanism)** — Eve calls these schedules/hooks; we call them habits (product decision) and back them with runtime-registered crons instead of static config |
-| *(no equivalent)* — bounded per-agent authority | not present in `vercel/eve` | `mandates` + `approvalRequests` child tables (`@convex-dev/rate-limiter` + `@convex-dev/sharded-counter`, see "Mandates & habits (T4)" below) | **notre ligne** — SYNTHESE §2 "la réponse à la peur de lâcher les commandes"; a weighted, data-driven spending cap per org+agent+scope, overrun => human approval request, never a silent workaround |
-| Session/turn resolver boundaries (`ALLOWED_DYNAMIC_INSTRUCTION_EVENTS = {session.started, turn.started}`) | `dynamic-tool-definition.ts:40-46` | `sessionEvents.name` union (`session.started`, `turn.started`, ...) + `engine/resolvers.ts:resolveManifest` | direct parity — same event names, same "reread the aggregate, never cache" contract |
-| VantagePeers tools (memory, tasks, messages, notes) as a connection | not in `vercel/eve` (no equivalent first-party integration) | `vpConnections` child table (4 booleans, ON by default) + `engine/vpConnection.invokeVpTool` (I6, mvp §2.2 "Travail d'équipe") | **notre ligne** — direct access, NOT network: dispatch is a caller-supplied Convex function handle (`createFunctionHandle`, same discipline as `wakeableWork.workId` / `durableJobs.stepFunctionHandle`), never a `fetch()` call. `orgId` is threaded explicitly into the target handle so a VP write always lands in the invoking agent's own org tenant (`engineDelegation.test.ts` proves both the write and the cross-org refusal) |
-| Agent directory, scoped by org | not in `vercel/eve` | `directory.listByOrg` (I6) | **notre ligne** — same `by_org` index discipline as every other list in this engine; reports each agent's subagent/connection counts alongside `agents.list` |
-| ~~`subagents` NOT used for inter-agent collaboration~~ | eve docs / mvp-evevantage.md §2.5 (T4-era decision) | superseded by I6 — see the delegation rows above | **REVISED, T6/I6**: the T4-era README claimed "la collaboration entre agents n'arrive pas par les `subagents` d'eve" (VantagePeers-only). I6 wires `subagents` up for real, by the SAME pause/wake mechanism as everything else in this engine (SYNTHESE §4.d) — VantagePeers connection tools (row above) remain available IN ADDITION, not as a replacement |
-| `outputSchema`, `compaction`, `modelOptions`, `channels` | `agent-definition.ts:124-146,313-330`, `manifest.ts:56-77` | out of scope this lot | left for a later I-cycle, documented as deliberately deferred (mvp §2.5) |
-
-## Data aggregate — schema (`convex/schema.ts`)
-
-Root sheet: `agents`.
-
-Child tables (>= 7, every index starts with `orgId`):
-
-1. `skills` — contextual procedures
-2. `subagents` — recursive declared delegation, strict isolation
-3. `connections` — MCP/OpenAPI (VantagePeers tools included)
-4. `habits` (+ `habitRuns`) — dynamic crons (habits, notre ligne, T4)
-5. `sandboxConfig` — Vercel Sandbox settings
-6. `toolApprovals` — `always` / `once` / `never` per tool
-7. `modelKeys` — BYOK, server-only, split from `agents`
-8. `mandates` (+ `approvalRequests`) — bounded authority (notre ligne, T4)
-9. `vpConnections` (+ `vpToolInvocations`) — VantagePeers connection toggles + audit trail (notre ligne, T6/I6)
-
-Engine tables: `sessions`, `sessionEvents`, `awaitEventTimeouts`,
-`delegationRuns`, `agentCloneRuns` (I6 — see "Delegation (T6/I6)" below).
-
-**Hard rule**: `orgId` is derived server-side from the authenticated
-identity (`convex/lib/auth.ts:requireOrgId`, reads the Clerk `org_id`
-claim) — it is never accepted as a client argument, and it is the FIRST
-field of every `.index(...)` call. Deny by default: cross-org reads return
-`null` / cross-org writes throw, indistinguishable from "not found"
-(`convex/lib/auth.ts:assertSameOrg`).
-
-## Engine — durable sessions (`convex/engine/`)
-
-- `engine/workflows.ts` — `WorkflowManager` from `@convex-dev/workflow`.
-  The session loop is exported as `sessionWorkflowV1`. **Versioned
-  workflows / drain-before-deploy discipline** (workflow#35): a breaking
-  change to the loop ships as `sessionWorkflowV2`, never an in-place edit
-  of `V1` while sessions still reference it.
-- `engine/resolvers.ts` — `resolveManifest`, the dynamic resolver. Rereads
-  the full agent aggregate (skills, tool approvals, connections) on every
-  call; callers invoke it at `session.started` / `turn.started` boundaries
-  only, mirroring eve's `ALLOWED_DYNAMIC_INSTRUCTION_EVENTS`.
-- `engine/sessions.ts` — `start` / `recordTurnStarted`, the mutations that
-  write the named `sessionEvents` rows Eve-style.
-- `engine/awaitEventTimeout.ts` — **self-built `awaitEvent` timeout**
-  (workflow#177: Convex ships no native timeout for `step.awaitEvent`).
-  `schedule` writes an `awaitEventTimeouts` row and schedules an
-  `internalMutation` (`fire`) via `ctx.scheduler.runAfter`; if the real
-  event arrives first, `cancel` cancels the scheduled function. `fire`
-  inserts a blank `sandbox.timeout` `sessionEvents` row so the awaiting
-  workflow step wakes up regardless.
-
-`ai` is pinned to `6.0.35` (peer dependency of `@convex-dev/agent@0.6.4`,
-agent#79 warns the v5->v6 migration broke other consumers — we track
-majors deliberately, never float). Counters/rollups, when needed, go
-through `@convex-dev/sharded-counter` / `@convex-dev/aggregate` — no
-canary/alpha third-party dependency for a guardrail (I0 §7.4).
-
-## Long-task survival (I1) — `engine/durableJob.ts`
-
-SYNTHESE.md §5/§7: "le plafond de durée des actions Convex est notre
-plafond aujourd'hui, sur tous nos produits" -- `durableJobs` is the
-GENERIC (shape-agnostic, unlike `sessions`) primitive that lets a
-consumer's task survive past that ceiling by expressing it as N
-independently-bounded steps. It **ENVELOPS** `@convex-dev/workflow` (via
-the same `WorkflowManager` + versioned-workflow discipline as
-`engine/workflows.ts`), it does not reimplement durable execution.
-
-Contract (see `convex/engine/durableJob.ts` for the full commentary and
-`examples/vantage-peers-long-task/` for the worked integration a consumer
-reads without needing to know our internals):
-
-- `start(kind, stepFunctionHandle, totalSteps, maxAttemptsPerStep)` —
-  enqueue a job driven by a step function the CALLER owns (component
-  isolation: we invoke it by opaque `FunctionHandle`, we never read the
-  caller's own tables).
-- `getStatus(jobId)` — poll `status` / `cursor` / `lastError` /
-  `abandonedAtStep`.
-- `cancel(jobId)` — best-effort stop.
-- **Pause at step boundary**: one loop iteration == one workflow step ==
-  one durability boundary (`@convex-dev/workflow` persists the journal
-  after each step returns).
-- **Deterministic replay**: `runStepInternal` no-ops for any `stepIndex <
-  job.cursor`, so a resumed workflow's journal replay never re-runs a
-  completed step.
-- **Abandon after N**: the caller's step function is retried up to
-  `maxAttemptsPerStep` times inside one workflow step; once exhausted the
-  job is marked `abandoned` with `abandonedAtStep` + `lastError`, and no
-  further step runs.
-
-## Mandates & habits (T4) — NOTRE LIGNE, EveVantage's two product differentiators
-
-SYNTHESE.md §2: *"Deux arguments de vente que personne n'a"* — mandates
-("cet agent peut engager jusqu'à X ; au-delà, il me demande") and habits
-("tous les matins, relève les mails, classe, fais le point"). Both are
-**declared divergences from `vercel/eve`** — Eve has no concept of a
-weighted spending cap or a runtime-editable recurrence; this is our line,
-not a silent gap.
-
-### Mandates — `convex/mandates.ts` (`mandates`, `approvalRequests` tables)
-
-**Notre ligne**: bounded authority per agent+org+scope. A mandate is a
-DATA ROW (`mandates.{kind,rate,period,capacity}`), never a constant in
-code — a client changing their mind is a `mandates.set` mutation, zero
-deploy. `spend(agentId, scope, cost, reason)` is the single choke point
-every costed action must pass through:
-
-- **fails-closed**: no mandate row for `orgId+agentId+scope` => throws
-  immediately (`Mandate refused: no mandate configured for scope "..."`).
-  There is no "unlimited by default" path.
-- **overrun => human approval, never a silent workaround**: when
-  `@convex-dev/rate-limiter`'s `limit()` (called with an **inline dynamic
-  `config`** built from the DB row — see rate-limiter README "Define a
-  rate limit inline / dynamically") returns `ok: false`, `spend` inserts
-  an `approvalRequests` row (`status: "pending"`) and returns
-  `{ ok: false, approvalId }`. It deliberately does **not** throw on this
-  path: Convex mutations are single transactions, and throwing after
-  `ctx.db.insert` would roll the insert back along with everything else —
-  destroying the very approval record the guard exists to leave behind.
-  Callers (the session/workflow engine) are REQUIRED to check `.ok` and
-  treat `false` as a hard refusal; the only way authority is restored is
-  an explicit human `resolveApproval(approvalId, "approved", resolvedBy)`.
-- **rollups via `@convex-dev/sharded-counter`** (`usageCount` query), one
-  bucket per `orgId:agentId:scope` key — I0 §7.4: no canary/alpha
-  dependency for a guardrail. `@convex-dev/aggregate` (also I0-approved,
-  also official, also no canary) is the natural next step for time-
-  windowed billing rollups; not wired in this lot, called out here rather
-  than silently left out.
-- `count` passed to `rateLimiter.limit` is a WEIGHTED cost (tokens, euros,
-  calls — whatever the scope means), never a bare call counter.
-
-### Habits — `convex/habits.ts` (`habits`, `habitRuns` tables)
-
-**Notre ligne (naming + mechanism)**: Eve's closest concept is
-`schedules`/`hooks`, statically declared in a compiled agent. Habits are
-runtime DATA: `habits.cronExpression` is a column, and the actual
-recurrence is a **dynamically registered `@convex-dev/crons` job**
-(`Crons.register`/`.delete`, never a static `convex/crons.ts` entry).
-
-- `create` writes the habit row and registers its cron in the SAME
-  mutation transaction — `@convex-dev/crons` guarantees the cron "is
-  guaranteed to exist after the mutation that creates them has run"
-  (README), so the very next tick can fire it with zero deploy.
-- `updateSchedule` edits `cronExpression`/`prompt`/`name` at runtime:
-  deletes the old cron registration, registers a fresh one from the new
-  cadence, still inside one transaction.
-- `disable` is a HARD stop: it deletes the runtime cron registration
-  (not a soft `enabled` flag the target function checks) — after it
-  resolves there is no scheduled function left that could fire the habit.
-  `run` (the cron-invoked internal mutation) also re-checks `enabled` as
-  defence in depth for any run already in flight.
-- `enable` re-registers from the habit's own `cronExpression` data.
-- Every tick writes a `habitRuns` proof row — this is what makes "fires
-  its first run without a deploy" and "a disabled habit does not fire
-  again" PROVABLE in `habits.test.ts` rather than asserted on trust.
-
-## Delegation (T6/I6) — `engine/delegation.ts`, `engine/vpConnection.ts`, `directory.ts`
-
-Bible: SYNTHESE §4.d — "un agent qui délègue à un autre agent = LE MÊME
-système pause/réveil (awaitEvent/sendEvent) que le pont sandbox — un seul
-système à écrire, pas deux".
-
-### (a) Two delegation semantics, both reusing `engine.wakeup.enqueue`
-
-- **Declared subagents** (`subagents` table, `engine/delegation.ts`):
-  strict isolation — `declareSubagent` writes ONLY the parent->child link +
-  the named tool (`toolName`); the child's own aggregate is the sole place
-  its skills/connections/toolApprovals ever live (read via
-  `engine/resolvers.resolveManifest` against a session on `childAgentId`).
-  **Build-time collision guard**: `toolName` must be unique against (1) the
-  reserved built-in `"agent"` tool name, (2) every other declared subagent
-  of the same parent (`by_org_parent_tool` index), (3) an existing
-  `toolApprovals` row on the parent — any collision REJECTS the mutation,
-  never a silent "last one wins" (eve.dev/docs/subagents, verbatim).
-- **Built-in `agent` tool** (`invokeAgentClone`, `agentCloneRuns` table):
-  a clone of the ROOT, root-only, NOT recursive. `viaAgentTool: true`
-  (a recursive attempt) is refused BEFORE any row is written or
-  `engine.wakeup.enqueue` is ever called.
-- **The reuse point**: `delegateToSubagent` and `invokeAgentClone` BOTH
-  terminate in exactly one call to the SAME public `engine.wakeup.enqueue`
-  action T4/I2 already ships (`ctx.runAction(api.engine.wakeup.enqueue,
-  ...)`) — no bespoke `onComplete`/`sendEvent` path exists in
-  `engine/delegation.ts`. `engine/delegationDemoWorkflow.ts` is the
-  reference parent-side recipient (same shape as
-  `engine/wakeupDemoWorkflow.ts`): it parks on `step.awaitEvent` and
-  resumes only when the delegate's work completes.
-
-### (b) VantagePeers connection — `engine/vpConnection.ts`
-
-Four toggles (`memoryEnabled`, `tasksEnabled`, `messagesEnabled`,
-`notesEnabled`), ON by default (mvp §2.2 "Travail d'équipe", "quatre
-interrupteurs cochés par défaut" — a missing `vpConnections` row means "use
-the defaults"). `invokeVpTool` dispatches via a caller-supplied Convex
-function handle (`createFunctionHandle`, same discipline as
-`wakeableWork.workId` / `durableJobs.stepFunctionHandle`) — **direct
-access, zero network in the hot path**:
-
-```
-$ grep -n "fetch(" convex/engine/vpConnection.ts convex/engine/delegation.ts
-(no matches)
+A reusable [Convex component](https://www.convex.dev/components) that
+provides a durable **agent engine**: sessions, delegation, tool approvals,
+scheduled "habits", bounded spending "mandates", and long-task survival —
+all built on top of
+[`@convex-dev/workflow`](https://www.npmjs.com/package/@convex-dev/workflow)
+and
+[`@convex-dev/workpool`](https://www.npmjs.com/package/@convex-dev/workpool).
+
+**An agent is a data aggregate, not compiled code.** Creating an agent means
+writing a row (plus child rows for skills, tool approvals, connections,
+sub-agents, habits, sandbox config) — there is no build step and no
+redeploy. This mirrors the authoring model pioneered by
+[vercel/eve](https://github.com/vercel/eve), whose slot names, contracts and
+vocabulary this package tracks closely; credit and thanks to that project for
+the design this component is built in parity with.
+
+## Why
+
+Most agent frameworks compile an agent definition into code that has to be
+deployed to change. This engine keeps the entire agent definition as
+database rows: skills, tool approvals, delegated sub-agents, sandbox
+settings, and scheduled work are all mutable at runtime through ordinary
+Convex mutations. Combined with `@convex-dev/workflow`'s durable execution,
+a single agent session — or a long-running background job — survives
+process restarts, Convex's per-action time limits, and redeploys of the
+consuming app.
+
+## Install
+
+```bash
+npm install @vantageos/agent-engine
 ```
 
-`orgId` is threaded explicitly into the target handle's args (never a
-client-supplied value, never the target's own `ctx.auth`), so a VP tool
-call always writes into the CALLING agent's own org tenant — proven in
-`engineDelegation.test.ts` alongside the cross-org refusal (an agent
-belonging to another org is "not found", same deny-by-default posture as
-everywhere else in this engine).
-
-### (c) Agent directory — `directory.ts`
-
-`directory.listByOrg` — every agent of the caller's own org (server-derived
-`orgId`, `by_org` index), plus each agent's subagent/connection counts.
-
-## `convex/_generated/` freshness -- two gates, not one
-
-`convex/_generated/api.d.ts` carries an "AUTOMATICALLY GENERATED" header
-but nothing stops a hand-edit of its *content* (as opposed to adding or
-removing an entire module) from being committed as-is. That gap was
-measured for real on PR #2 (T2-BIS): a manual edit of a single existing
-line (`FunctionReference<any, "public">` flipped to `"internal">`) passed
-the original structural gate with `OK`, because that gate only diffs the
-*list* of modules present under `convex/` against the modules imported by
-`api.d.ts` -- it never recomputes a byte.
-
-Two gates now exist, and they check different things:
-
-1. **Structural, offline, secret-free** --
-   `scripts/check-generated-freshness.mjs` (`npm run check:generated`).
-   Runs in CI (`.github/workflows/ci.yml`). Catches a function file
-   added/renamed/removed without regenerating bindings. **Does NOT catch a
-   hand-edit of existing generated content.**
-2. **Content, requires a live deployment** --
-   `scripts/check-generated-content.mjs` (`npm run
-   check:generated:content`). Runs `npx convex codegen` against the dev
-   deployment for BOTH `convex/_generated/` (the host repo's own dev
-   deployment bindings) AND, since 0.1.0-alpha.5, `component/_generated/`
-   via `npx convex codegen --component-dir component` -- the checked-in
-   file `tsc -p tsconfig.build.json` copies verbatim into the PUBLISHED
-   `dist/component/_generated/component.d.ts`, i.e. the exact type a
-   consuming app checks `components.agentEngine.*` calls against. Diffs
-   each byte-for-byte (`git diff --exit-code`). Catches everything,
-   including a single hand-edited character.
-
-   **`component/_generated/` was NOT covered before 0.1.0-alpha.5** — that
-   gap is why `0.1.0-alpha.4` shipped a `component.d.ts` stale against the
-   real component schema (missing `orgId`/`createdBy` on
-   sessions/agents/durableJob/toolApprovals args), which broke
-   `tsc --noEmit` for any consumer calling `sessions.start`/`durableJob.start`
-   with `orgId` (Hestia, VP k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 1).
-   The visibility (`"internal"`) on every entry is, by measured comparison
-   against `@convex-dev/rate-limiter`'s own published `component.d.ts`,
-   CORRECT and unrelated to that defect — every official Convex component
-   types its cross-component `ComponentApi` as `"internal"` regardless of
-   whether the underlying function is declared `mutation`/`query` or
-   `internalMutation`/`internalQuery`; `ctx.runMutation`'s own signature
-   (`convex/server`) accepts `FunctionReference<"mutation", "public" |
-   "internal">` either way. The root cause was staleness of the args
-   shape, not visibility.
-
-   **Three-state exit contract** (never two -- a two-state gate cannot
-   distinguish "I measured, it's clean" from "I could not measure at
-   all", and collapsing those is either a silent fail-open or a red that
-   proves nothing; see flotte rule `three-state-verdict.md`):
-
-   | Exit | Meaning | When |
-   | ---- | ------- | ---- |
-   | `0` | **PASS** | A real measurement was taken (`npx convex codegen` ran) and `convex/_generated/` is byte-identical to its output. |
-   | `1` | **VIOLATION** | A real measurement was taken and it found >=1 byte of divergence -- hand-edited, stale, or generated against a different schema. |
-   | `2` | **REFUSAL TO JUDGE** | `npx convex codegen` itself could not run (no live, authenticated Convex deployment reachable -- `CONVEX_DEPLOYMENT` / `.env.local` missing or invalid). No measurement was taken; this is neither a clean bill of health nor a proven violation. |
-
-### CI cannot run the content gate -- explicit limit, not a rounding error
-
-`npx convex codegen` has no offline mode: it always needs
-`CONVEX_DEPLOYMENT` / a deploy key against a live deployment. This repo
-refuses to store that as a CI secret (plan B, PR #1). **Consequence,
-stated plainly: CI cannot detect a hand-edited `convex/_generated/`
-content change.** CI only runs the structural gate. The content gate is
-the only thing that catches a content-level tamper, and it can only run
-where the secret lives: **locally, pre-commit**, via `.env.local`.
-
-To install the pre-commit gate once per clone:
+## Quickstart
 
-```
-git config core.hooksPath scripts/git-hooks
-```
-
-This points git at the versioned hook `scripts/git-hooks/pre-commit`
-(plain git hook, not a Claude hook -- Claude hooks under `.claude/hooks/`
-are Pi-owned only). The hook no-ops unless a staged file is under
-`convex/`, and then runs `npm run check:generated:content`, reading its
-exit code explicitly rather than treating it as a boolean:
-
-- `0` (PASS) -- commit proceeds.
-- `1` (VIOLATION) -- commit is **blocked**, message names the divergence.
-- `2` (REFUSAL TO JUDGE, e.g. `.env.local` deployment secret missing or
-  invalid) -- commit is **also blocked**, with a distinct message that
-  says explicitly this is *unverified*, not a proven violation. This is a
-  deliberate fail-closed choice: an unverified change to `convex/_generated/`
-  content must never slip through silently just because the local
-  instrument (a live Convex deployment) was unavailable. The trade-off is
-  that a developer without a working `.env.local` cannot commit to
-  `convex/**` at all until they fix their local deployment credentials --
-  judged the safer failure mode than a fail-open that would let a hand-
-  edited, un-regenerated `convex/_generated/` through whenever the secret
-  happens to be missing.
-
-**If `core.hooksPath` is never configured, this protection does not
-exist on that clone.** Nothing currently makes that configuration
-mandatory or automatic -- that decision (e.g. via a repo bootstrap script
-that all contributors run) is Pi's to make, not this PR's.
-
-## Tests (TDD, RED then GREEN)
-
-- `convex/agents.test.ts` — org isolation (family 1)
-- `convex/engineResolvers.test.ts` — dynamic resolver, no-redeploy (family 2)
-- `convex/engineAwaitEventTimeout.test.ts` — awaitEvent timeout wakes the
-  workflow when the real event never arrives (family 3)
-- `convex/engineDurableJob.test.ts` — I1 long-task survival contract
-  (family 4): a 25-step job survives to `completed` via the component; a
-  replayed already-completed step is a proven no-op (resume after forced
-  interruption); a step that always fails is retried and the job is
-  `abandoned` (never touching the next step); a step that fails once then
-  succeeds still reaches `completed`; cross-org `getStatus` is denied.
-- `convex/mandates.test.ts` — mandates, three-pole probe: MUST_PASS (spend
-  under cap succeeds, rollup counts it), MUST_BLOCK (spend at cap is
-  refused, `approvalRequests` row created), MUST_REFUSE (no mandate
-  configured => fails-closed, names the missing scope, no approval row
-  created) + org isolation + human `resolveApproval`.
-- `convex/habits.test.ts` — habits, three-pole probe: MUST_PASS (a habit
-  created at runtime fires its first run with zero deploy), MUST_BLOCK (a
-  disabled habit does not fire again after further clock advances),
-  MUST_REFUSE (`enable` on an already-enabled habit is a documented
-  no-op, not a silent double-registration) + full runtime lifecycle
-  (create / updateSchedule / disable / enable, no redeploy at any step).
-- `component/durableJob.componentPackaging.test.ts` — the SAME contract
-  (long job survives, abandon-after-N, org isolation, cancel), but run
-  against `component/_generated/api` — the exact source tree compiled to
-  `dist/component/` and published — proving the migrated, packaged code
-  itself, not only the repo-root dev app.
-- `convex/engineWakeup.test.ts` — I2 wake-up primitive (`enqueue` ->
-  `onComplete` -> `sendEvent`), three-pole probe + org isolation.
-- `convex/engineSandboxCallback.test.ts` — I5 sandbox bridge (signed
-  callback, dedup, timeout, dead-letter).
-- `convex/engineDelegation.test.ts` — I6 delegation, three-pole probe:
-  MUST_PASS (a declared subagent's manifest carries only its own skills;
-  `declareSubagent` succeeds on a fresh name; `invokeAgentClone` succeeds
-  for a first-level call; VP toggles default ON; `invokeVpTool` writes
-  into the calling org's tenant; `directory.listByOrg` scoped to the
-  caller's org), MUST_BLOCK (a subagent tool-name collision with an
-  existing tool OR the reserved `"agent"` name is rejected and writes
-  nothing; a recursive `invokeAgentClone` call is refused before any row
-  is written; a cross-org `invokeVpTool` call is refused; a disabled VP
-  tool is refused; zero `fetch(` calls in the VP connection hot path),
-  MUST_REFUSE (every mutation/action above with no identity names
-  "Unauthenticated" rather than crashing unreadably).
-- `convex/engineDelegationDemo.test.ts` — the real pause/wake delegation
-  demo (A delegates to B via `engine.delegation.delegateToSubagent`, B's
-  work completes through `wakeupPool`, A's parked workflow resumes),
-  console-logged verbatim (`[i6-demo]` prefix) and kept in its own file
-  because it drives `vi.useFakeTimers()` through more event-loop pumps
-  than the rest of the suite.
-
-Run: `npx vitest run` (or `npm test`).
-
-## Packaging & publication (T2-TER, functions since T2-QUATER)
-
-`@vantageos/agent-engine` is published to npm under the `alpha` dist-tag
-(`npm view @vantageos/agent-engine version` / `dist-tags`, read from the
-registry after publish, never from `npm publish`'s own exit status). The
-package exposes a resolvable `"./convex.config"` subpath (types + JS,
-built by `npm run build` from `component/convex.config.ts` via
-`tsc -p tsconfig.build.json` into `dist/component/`), so a consumer's
-`convex/convex.config.ts` can do:
+Register the component in your app's `convex/convex.config.ts`:
 
 ```ts
 import { defineApp } from "convex/server";
@@ -429,265 +46,218 @@ app.use(agentEngine);
 export default app;
 ```
 
-### Trust model — READ THIS FIRST (CORRECTIF, VP k1741evjzm72rj91tkcbdhpskx8ah35a)
-
-**Convex does not propagate the calling app's `ctx.auth` identity across a
-component boundary.** This is a platform isolation guarantee, not a choice
-this package makes (`convex-test` states it verbatim: "Auth doesn't
-propagate across component boundaries"). A function inside this component
-therefore can NEVER read `ctx.auth.getUserIdentity()` and expect it to
-reflect the consumer app's end user.
-
-**`orgId` is an explicit ARGUMENT on every public function in this
-component.** The calling app is responsible for authenticating its user and
-resolving that user's `orgId` on its OWN side (e.g. reading a Clerk
-org-scoped claim from its own `ctx.auth`) BEFORE calling into this
-component — this component cannot do that step for you, it is a platform
-constraint, not a design preference.
-
-What did NOT change: the component still denies by default
-(`lib/auth.ts:requireOrgId` throws on a missing/empty `orgId`), `orgId` is
-still the first field of every index, and every document fetched by `_id`
-is still checked with `lib/auth.ts:assertSameOrg` before being returned or
-mutated — a caller-supplied `orgId` can never read or write another org's
-rows. The isolation boundary moved from "component reads `ctx.auth`"
-(impossible across a component boundary) to "component enforces the
-`orgId` argument the consumer already vouches for"; deny-by-default,
-orgId-first-index, no-cross-org-reads are unchanged.
-
-### What's callable, and what isn't (read this before wiring a consumer)
-
-`component/` (sibling of `convex/`, NOT nested under it — see "Why
-`component/` and not `convex/component/`" below) hosts the **actual,
-compiled, published functions** for the FULL agent aggregate as of
-0.1.0-alpha.6 (C1-C6, all merged) — not just the component's identity:
-
-- `component/schema.ts` — `durableJobs`, `agents`, `toolApprovals`,
-  `sessions`, `sessionEvents`, `wakeableWork`, `awaitEventTimeouts`,
-  `mandates`, `approvalRequests`, `habits`, `habitRuns`, `sandboxConfig`,
-  `sandboxRuns`, `sandboxCallbackDeliveries`, `sandboxCallbackDeadLetters`,
-  `subagents`, `delegationRuns`, `agentCloneRuns`, `vpConnections`,
-  `vpToolInvocations` (+ test-only fixture tables: `callerStepInvocations`,
-  `wakeupDemoResults`, `vpTenantFixture`).
-- `component/engine/durableJob.ts` — `start` / `getStatus` / `cancel`
-  (public contract) + `durableJobWorkflowV1` (the versioned pause/resume/
-  replay workflow) + its internal step-runner mutations.
-- `component/engine/agents.ts` — `create` / `get` (root-sheet bootstrap,
-  now including `description`/`reasoningEffort`/`modelProvider`/
-  `maxSubagents`/`maxInputTokensPerSession`; `update`/skills/connections
-  CRUD remain out of scope for this pass).
-- `component/engine/directory.ts` — `listByOrg` (agent directory listing).
-- `component/engine/resolvers.ts` — `resolveManifest` (dynamic reread at
-  session/turn boundaries; returns `agentId`/`name`/`instructions`/`model`/
-  `toolApprovals` — `skills`/`connections` NOT included in this pass).
-- `component/engine/sessions.ts` — the conversation thread contract:
-  `start` / `sendTurn` / `appendReasoning` / `requestToolCall` /
-  `completeToolCall` / `completeTurn` / `listEvents`, now piloted by a
-  versioned `@convex-dev/workflow` run (`sessionWorkflowV1`,
-  `component/engine/workflows.ts` — C1.5).
-  `sessions.start` returns `{ sessionId, workflowId }`.
-- `component/engine/toolApprovals.ts` — `respond`.
-- `component/engine/wakeup.ts` — `enqueue` / `cancel` / `getStatus` +
-  `onWorkComplete` (the wake-without-polling primitive; funds through
-  `mandates.spendInternal` before any work enters the pool — C2/C3 seam).
-- `component/engine/awaitEventTimeout.ts` — self-built `step.awaitEvent`
-  timeout (workflow#177: Convex has no native timeout for it).
-- `component/engine/mandates.ts` — `set` / `get` / `spend` /
-  `listApprovals` / `resolveApproval` / `usageCount` (autorité bornée,
-  fails-closed spend gate; "notre ligne").
-- `component/engine/habits.ts` — `create` / `get` / `listForAgent` /
-  `updateSchedule` / `disable` / `enable` / `listRuns` (per-agent dynamic
-  cron, zero-redeploy lifecycle via `@convex-dev/crons`; "notre ligne").
-- `component/engine/sandboxCallback.ts` — `startRun` / `attachSandboxId` /
-  `getStatus` / `deadLetterMalformed` / `processCallback` (the DB-side
-  half of the Vercel Sandbox bridge: dedup + wake + timeout, reusing C2's
-  `wakeup` mechanism).
-- `component/engine/delegation.ts` — `declareSubagent` / `listSubagents` /
-  `delegateToSubagent` / `invokeAgentClone` (inter-agent delegation and the
-  built-in `agent` clone tool, both reusing `wakeup.enqueue` — the SAME
-  pause/wake mechanism as the sandbox bridge, one system not two).
-- `component/engine/vpConnection.ts` — `get` / `getToggles` / `setToggles`
-  / `invokeVpTool` (the four VantagePeers tools — memory/tasks/messages/
-  notes — wired as a connection of the agent aggregate; "notre ligne").
-- `component/lib/auth.ts` — `requireOrgId` / `assertSameOrg`: see "Trust
-  model" above.
-
-**Callable through the published component today** — every function below
-takes `orgId: v.string()` as an explicit argument (see the source files
-above for the exact `v.*` shapes of the remaining args/returns):
+Then call into it from your own Convex functions. Every public function
+takes an explicit `orgId: string` argument — Convex does not propagate the
+calling app's `ctx.auth` identity across a component boundary, so your app
+is responsible for resolving the caller's org before calling in:
 
+```ts
+import { components } from "./_generated/api";
+
+export const createAgent = mutation({
+  args: { orgId: v.string(), name: v.string(), instructions: v.string() },
+  handler: async (ctx, args) => {
+    return ctx.runMutation(components.agentEngine.engine.agents.create, {
+      orgId: args.orgId,
+      createdBy: "user_123",
+      name: args.name,
+      instructions: args.instructions,
+      model: "gpt-4o",
+    });
+  },
+});
 ```
-components.agentEngine.engine.durableJob.start({ orgId, kind, stepFunctionHandle, totalSteps, maxAttemptsPerStep }) -> Id<"durableJobs">
-components.agentEngine.engine.durableJob.getStatus({ orgId, jobId }) -> { status, cursor, totalSteps, lastError?, abandonedAtStep? }
-components.agentEngine.engine.durableJob.cancel({ orgId, jobId }) -> null
 
-components.agentEngine.engine.agents.create({ orgId, createdBy, name, description?, instructions, model, reasoningEffort?, modelProvider?, maxSubagents?, maxInputTokensPerSession? }) -> Id<"agents">
-components.agentEngine.engine.agents.get({ orgId, agentId }) -> agent | null
-
-components.agentEngine.engine.directory.listByOrg({ orgId }) -> { _id, name, status, model, createdAt }[]
+## What's inside
 
-components.agentEngine.engine.resolvers.resolveManifest({ orgId, sessionId }) -> { agentId, name, instructions, model, toolApprovals[] }
+The component's data model (root table `agents`, plus child tables for
+skills, sub-agents, connections, habits, sandbox config, and per-tool
+approvals) is deployed under the Convex component boundary your app
+registers — it does not touch your own app's tables, and every index is
+scoped by `orgId` first, deny-by-default.
 
-components.agentEngine.engine.sessions.start({ orgId, agentId, createdBy }) -> { sessionId: Id<"sessions">, workflowId: string }
-components.agentEngine.engine.sessions.sendTurn({ orgId, sessionId, input }) -> null
-components.agentEngine.engine.sessions.appendReasoning({ orgId, sessionId, chunk }) -> null
-components.agentEngine.engine.sessions.requestToolCall({ orgId, sessionId, toolName, argsJson }) -> { authorized, approvalPending, denied }
-components.agentEngine.engine.sessions.completeToolCall({ orgId, sessionId, toolName, resultJson }) -> null
-components.agentEngine.engine.sessions.completeTurn({ orgId, sessionId }) -> null
-components.agentEngine.engine.sessions.listEvents({ orgId, sessionId }) -> sessionEvent[]
+### API surface (component/, current release)
 
-components.agentEngine.engine.toolApprovals.respond({ orgId, sessionId, toolName, decision: "approved"|"denied", updatePolicy?: "always"|"once"|"never" }) -> null
+```
+components.agentEngine.engine.agents.create({
+  orgId, createdBy, name, description?, instructions, model,
+  reasoningEffort?, modelProvider?, maxSubagents?,
+  maxInputTokensPerSession?,
+}) -> Id<"agents">
+components.agentEngine.engine.agents.get({ orgId, agentId }) -> agent | null
 
-components.agentEngine.engine.wakeup.enqueue({ orgId, agentId, mandateScope, cost, reason, workFunctionHandle, workflowId, awaitedEventName }) -> Id<"wakeableWork">  (action)
+components.agentEngine.engine.directory.listByOrg({ orgId })
+  -> { _id, name, status, model, createdAt }[]
+
+components.agentEngine.engine.resolvers.resolveManifest({
+  orgId, sessionId,
+}) -> { agentId, name, instructions, model, toolApprovals[] }
+
+components.agentEngine.engine.sessions.start({
+  orgId, agentId, createdBy,
+}) -> { sessionId: Id<"sessions">, workflowId: string }
+components.agentEngine.engine.sessions.sendTurn({
+  orgId, sessionId, input,
+}) -> null
+components.agentEngine.engine.sessions.appendReasoning({
+  orgId, sessionId, chunk,
+}) -> null
+components.agentEngine.engine.sessions.requestToolCall({
+  orgId, sessionId, toolName, argsJson,
+}) -> { authorized, approvalPending, denied }
+components.agentEngine.engine.sessions.completeToolCall({
+  orgId, sessionId, toolName, resultJson,
+}) -> null
+components.agentEngine.engine.sessions.completeTurn({
+  orgId, sessionId,
+}) -> null
+components.agentEngine.engine.sessions.listEvents({
+  orgId, sessionId,
+}) -> sessionEvent[]
+
+components.agentEngine.engine.toolApprovals.respond({
+  orgId, sessionId, toolName,
+  decision: "approved"|"denied",
+  updatePolicy?: "always"|"once"|"never",
+}) -> null
+
+components.agentEngine.engine.wakeup.enqueue({
+  orgId, agentId, mandateScope, cost, reason,
+  workFunctionHandle, workflowId, awaitedEventName,
+}) -> Id<"wakeableWork">  (action)
 components.agentEngine.engine.wakeup.cancel({ orgId, wakeableWorkId }) -> null
-components.agentEngine.engine.wakeup.getStatus({ orgId, wakeableWorkId }) -> { status, resultSummary?, ... }
-
-components.agentEngine.engine.mandates.set({ orgId, agentId, scope, kind, rate, period, capacity? }) -> Id<"mandates">
-components.agentEngine.engine.mandates.get({ orgId, agentId, scope }) -> mandate | null
-components.agentEngine.engine.mandates.spend({ orgId, agentId, scope, cost, reason }) -> { ok, approvalId? }
-components.agentEngine.engine.mandates.listApprovals({ orgId, agentId }) -> approvalRequest[]
-components.agentEngine.engine.mandates.resolveApproval({ orgId, approvalId, resolvedBy, status: "approved"|"denied" }) -> null
-components.agentEngine.engine.mandates.usageCount({ orgId, agentId, scope }) -> number
+components.agentEngine.engine.wakeup.getStatus({
+  orgId, wakeableWorkId,
+}) -> { status, resultSummary?, ... }
+
+components.agentEngine.engine.durableJob.start({
+  orgId, kind, stepFunctionHandle, totalSteps, maxAttemptsPerStep,
+}) -> Id<"durableJobs">
+components.agentEngine.engine.durableJob.getStatus({ orgId, jobId })
+  -> { status, cursor, totalSteps, lastError?, abandonedAtStep? }
+components.agentEngine.engine.durableJob.cancel({ orgId, jobId }) -> null
 
-components.agentEngine.engine.habits.create({ orgId, agentId, name, cronExpression, prompt }) -> Id<"habits">
+components.agentEngine.engine.mandates.set({
+  orgId, agentId, scope, kind, rate, period, capacity?,
+}) -> Id<"mandates">
+components.agentEngine.engine.mandates.get({
+  orgId, agentId, scope,
+}) -> mandate | null
+components.agentEngine.engine.mandates.spend({
+  orgId, agentId, scope, cost, reason,
+}) -> { ok, approvalId? }
+components.agentEngine.engine.mandates.listApprovals({
+  orgId, agentId,
+}) -> approvalRequest[]
+components.agentEngine.engine.mandates.resolveApproval({
+  orgId, approvalId, resolvedBy, status: "approved"|"denied",
+}) -> null
+components.agentEngine.engine.mandates.usageCount({
+  orgId, agentId, scope,
+}) -> number
+
+components.agentEngine.engine.habits.create({
+  orgId, agentId, name, cronExpression, prompt,
+}) -> Id<"habits">
 components.agentEngine.engine.habits.get({ orgId, habitId }) -> habit | null
 components.agentEngine.engine.habits.listForAgent({ orgId, agentId }) -> habit[]
-components.agentEngine.engine.habits.updateSchedule({ orgId, habitId, cronExpression }) -> null
+components.agentEngine.engine.habits.updateSchedule({
+  orgId, habitId, cronExpression,
+}) -> null
 components.agentEngine.engine.habits.disable({ orgId, habitId }) -> null
 components.agentEngine.engine.habits.enable({ orgId, habitId }) -> null
 components.agentEngine.engine.habits.listRuns({ orgId, habitId }) -> habitRun[]
 
-components.agentEngine.engine.sandboxCallback.startRun({ orgId, workflowId, awaitedEventName, timeoutMs }) -> Id<"sandboxRuns">
-components.agentEngine.engine.sandboxCallback.attachSandboxId({ orgId, sandboxRunId, sandboxId }) -> null
-components.agentEngine.engine.sandboxCallback.getStatus({ orgId, sandboxRunId }) -> { status, resultSummary?, ... }
-components.agentEngine.engine.sandboxCallback.processCallback({ orgId, sandboxRunId, deliveryId, status, resultSummary? }) -> { outcome: "woke"|"duplicate" }   (called ONLY after the app-level HTTP route has verified the HMAC signature — see "notre ligne" below)
-components.agentEngine.engine.sandboxCallback.deadLetterMalformed({ orgId?, deliveryId, reason, rawBody }) -> null
-
-components.agentEngine.engine.delegation.declareSubagent({ orgId, parentAgentId, childAgentId, toolName, description? }) -> Id<"subagents">
-components.agentEngine.engine.delegation.listSubagents({ orgId, parentAgentId }) -> subagent[]
-components.agentEngine.engine.delegation.delegateToSubagent({ orgId, subagentId, ... }) -> null   (action; reuses `wakeup.enqueue` end to end)
-components.agentEngine.engine.delegation.invokeAgentClone({ orgId, agentId, ... }) -> null   (action; the built-in `agent` clone tool, root-only, non-recursive by construction)
-
-components.agentEngine.engine.vpConnection.get({ orgId, agentId }) -> vpConnection | null
-components.agentEngine.engine.vpConnection.getToggles({ orgId, agentId }) -> { memoryEnabled, tasksEnabled, messagesEnabled, notesEnabled }
-components.agentEngine.engine.vpConnection.setToggles({ orgId, agentId, memoryEnabled?, tasksEnabled?, messagesEnabled?, notesEnabled? }) -> Id<"vpConnections">
-components.agentEngine.engine.vpConnection.invokeVpTool({ orgId, agentId, tool, vpFunctionHandle, argsJson }) -> null   (action; direct access via `createFunctionHandle`, never `fetch()`)
+components.agentEngine.engine.sandboxCallback.startRun({
+  orgId, workflowId, awaitedEventName, timeoutMs,
+}) -> Id<"sandboxRuns">
+components.agentEngine.engine.sandboxCallback.attachSandboxId({
+  orgId, sandboxRunId, sandboxId,
+}) -> null
+components.agentEngine.engine.sandboxCallback.getStatus({
+  orgId, sandboxRunId,
+}) -> { status, resultSummary?, ... }
+components.agentEngine.engine.sandboxCallback.processCallback({
+  orgId, sandboxRunId, deliveryId, status, resultSummary?,
+}) -> { outcome: "woke"|"duplicate" }
+components.agentEngine.engine.sandboxCallback.deadLetterMalformed({
+  orgId?, deliveryId, reason, rawBody,
+}) -> null
+
+components.agentEngine.engine.delegation.declareSubagent({
+  orgId, parentAgentId, childAgentId, toolName, description?,
+}) -> Id<"subagents">
+components.agentEngine.engine.delegation.listSubagents({
+  orgId, parentAgentId,
+}) -> subagent[]
+components.agentEngine.engine.delegation.delegateToSubagent({
+  orgId, subagentId, ...,
+}) -> null   (action)
+components.agentEngine.engine.delegation.invokeAgentClone({
+  orgId, agentId, ...,
+}) -> null   (action; root-only, non-recursive by construction)
+
+components.agentEngine.engine.vpConnection.get({
+  orgId, agentId,
+}) -> vpConnection | null
+components.agentEngine.engine.vpConnection.getToggles({
+  orgId, agentId,
+}) -> { memoryEnabled, tasksEnabled, messagesEnabled, notesEnabled }
+components.agentEngine.engine.vpConnection.setToggles({
+  orgId, agentId, memoryEnabled?, tasksEnabled?,
+  messagesEnabled?, notesEnabled?,
+}) -> Id<"vpConnections">
+components.agentEngine.engine.vpConnection.invokeVpTool({
+  orgId, agentId, tool, vpFunctionHandle, argsJson,
+}) -> null   (action)
 ```
 
-**Deliberately app-level, NOT ported into the component boundary** — this
-is a measured platform boundary (C5 recherche-d'abord), not an unfinished
-migration:
-
-- The public HTTP route (`/sandbox/callback`) that reads
-  `SANDBOX_CALLBACK_SECRET` and verifies the HMAC signature over the raw
-  request body. No official `@convex-dev/*` component ships an `http.ts`
-  or reads `process.env` directly (measured: zero hits across all 7
-  installed `@convex-dev/*` component dist trees) — a component cannot
-  own this. It stays in the consumer app's own `convex/http.ts`, which
-  calls `sandboxCallback.processCallback` / `deadLetterMalformed` ONLY
-  after the signature has already checked out.
-- The `"use node"` action that actually talks to `@vercel/sandbox`
-  (`Sandbox.create()` / `sandbox.runCommand()`). The Convex CLI's own
-  component bundler hard-crashes on any `"use node"` file found inside a
-  child component directory ("use node directive is not supported in
-  components"). It stays app-level and calls INTO this component's public
-  `sandboxCallback.startRun` / `attachSandboxId` (and `mandates.spend`)
-  instead.
-
-Everything else that was previously listed as "not yet callable" —
-`skills`/`subagents`/`habits`/`sandboxConfig`/`mandates`/
-`approvalRequests`/`awaitEventTimeouts`/`wakeableWork`/`engine/wakeup.ts`/
-`engine/workflows.ts`/`vpConnections` — is now hosted under `component/`
-and callable as listed above (C1 through C6, this pass). `skills` and
-`connections` (the agent's own tool-definition and third-party-connection
-tables, distinct from the `subagents`/`vpConnections` tables above) remain
-the one genuinely deferred slice: porting them needs their own
-component-level `convex-test` harness first (Day 128: never ship
-unverified), and is left for the next, separately-scoped migration.
-
-### `toolApprovals.respond` — `decision` vs `updatePolicy` (0.1.0-alpha.5)
-
-Two DISTINCT axes were conflated pre-alpha.5 (VP
-k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2) — a single `approval:
-"always"|"once"|"never"` argument was overloaded to mean both "the standing
-policy for this tool" AND "the answer to this one pending request", and
-there was no literal for "refuse this turn only". Fixed by splitting them:
-
-- **`decision`** (required) — the response to THIS ONE pending
-  `tool.approval.requested` event, for THIS turn only. `"approved"` |
-  `"denied"`. **Eve parity, direct** — vocabulary matches Eve's
-  `ApprovalStatus` (`packages/eve/src/public/definitions/approval.ts`:
-  `"approved" | "denied" | "not-applicable" | "user-approval" | ...`); we
-  did not invent a `deny` literal, we aligned with the one Eve already has.
-  `"denied"` is a terminal refusal for the turn: `sessions.requestToolCall`
-  reports back `{ authorized: false, approvalPending: false, denied: true
-  }` (never re-authorized on retry within the session), and a dedicated
-  `turn.toolCall.denied` sessionEvent is appended — there is NO
-  `turn.toolCall.completed` for a denied call, i.e. the tool was never run
-  and the turn is NOT silently treated as done.
-- **`updatePolicy`** (optional) — persists a NEW standing gate
-  (`"always"|"once"|"never"`, eve parity: `eve/tools/approval` helpers) for
-  this `(agentId, toolName)` pair going forward, independent of `decision`.
-  A human can deny this turn's call and leave the policy alone (ask again
-  next time), or approve this turn and simultaneously flip the policy to
-  `"always"`/`"never"` so future calls stop pausing. `"never"` still means
-  Eve's "never require approval" (auto-authorize) — that policy literal is
-  unchanged and is NOT the same thing as a `"denied"` decision.
-
-`createdBy` (on `agents.create` / `sessions.start`) is, for the same
-platform reason as `orgId`, no longer read from `ctx.auth.getUserIdentity()`
-— the consumer passes the acting user's own identifier.
-
-Verified two ways: (1) every `component/*.componentPackaging.test.ts` file
-(one per migrated module: durableJob, sessions, directory, wakeup,
-awaitEventTimeout, mandates, habits, sandboxCallback, delegation,
-vpConnection) runs `convex-test` directly against `component/_generated/api`
-(the exact source tree `tsc -p tsconfig.build.json` compiles into
-`dist/component/`, which is what `npm pack` ships), so the compiled
-artifact has a real green test suite behind it, not just the repo-root dev
-app's; (2) a from-scratch global consumer probe (install the REAL
-`npm pack` tarball into a bare Convex project outside this repo, register
-the component, call one function from EACH migrated capability from the
-consumer's own function, passing `orgId` explicitly) — see the C7
-completion report for the verbatim transcript and, honestly, whichever
-parts of it required deployment provisioning this repo does not have.
-
-Only `skills` and `connections` (the agent's own tool-definition and
-third-party-connection tables) remain genuinely NOT ported — see
-"Deliberately app-level" and the closing paragraph above for the full,
-current boundary.
-
-### Why `component/` and not `convex/component/`
-
-`npx convex codegen --component-dir <path>` builds a synthetic root app
-that does `import component from "<relative-import-to-path>"`. When
-`<path>` is nested INSIDE the functions directory it resolves from
-(`convex/`), that relative import comes out as a bare specifier with no
-leading `./` or `../` (e.g. `"component/convex.config.js"`), which esbuild
-correctly refuses to resolve as a relative path — not a bug in our code,
-a corner case of running `--component-dir` against a directory nested
-under the default functions directory. Moving the component's source tree
-one level up, to `component/` (a sibling of `convex/`, mirroring how
-`@convex-dev/workflow` itself keeps its component source under `src/component`,
-outside its `example/convex` app directory) makes the generated relative
-import start with `../`, which resolves — measured empirically against
-this exact repo layout, not guessed.
-
-## Status
-
-T1 (schema + durable session engine, PR #1) merged @
-`9f3401ba63e6e663af95e9e4f5da42bc30b3550b`. I1 (long-task survival
-contract, `engine/durableJob.ts`) — not merged, Eta reviews. T4 (mandates
-+ habits) — **not merged** — Eta reviews, merge on Pi token. T2-TER (npm
-packaging + component identity + publication) through C6 (agents,
-sessions/workflow, directory, wakeup, awaitEventTimeout, mandates, habits,
-sandbox bridge DB-side, delegation, VantagePeers connection — all ported
-under `component/` with their own green `convex-test` suite) — see
-"Packaging & publication" above.
-
-**M-COMPLETION C7** (this pass): version bump to `0.1.0-alpha.6`
-republishing the FULL C1-C6 surface + a from-scratch global consumer probe
-against the real `npm pack` tarball proving packaged surface == built
-surface. npm `latest`/`alpha` tags are NOT repointed by this PR — that is
-a post-merge deployment step, Pi token protocol, same as every prior
-publish. See the C7 completion report for the probe transcript.
+### Concepts
+
+- **Sessions** — a durable conversation thread, driven by a versioned
+  `@convex-dev/workflow` run. Turns, streamed reasoning, tool-call
+  lifecycle and approval lifecycle are appended as an event log a client
+  replays on reconnect.
+- **Delegation** — an agent can declare typed sub-agents (strict isolation:
+  a sub-agent's own skills/connections/approvals are never copied onto the
+  parent) or invoke a non-recursive clone of itself as a built-in tool.
+  Both mechanisms reuse the same pause/wake primitive.
+- **Mandates** — a bounded, weighted spending cap per agent/org/scope.
+  Spending under the cap succeeds; an overrun creates a pending approval
+  request rather than silently failing open or throwing away the audit
+  trail.
+- **Habits** — a per-agent, runtime-editable cron schedule (create, update,
+  disable, enable — all with zero redeploy).
+- **Long-task survival** — `durableJob` lets a consumer's task survive past
+  a single Convex action's execution-time ceiling by expressing it as N
+  independently-bounded, resumable steps.
+
+### Trust model
+
+Convex does not propagate the calling app's `ctx.auth` identity across a
+component boundary. Every public function in this component takes `orgId`
+(and, where relevant, `createdBy`) as an explicit argument — your app is
+responsible for authenticating its user and resolving `orgId` before
+calling in. Every document lookup by id is checked against the caller's own
+`orgId` before being returned or mutated; a cross-org read or write is
+refused the same way a not-found row would be.
+
+## Requirements
+
+- Convex `^1.42`
+- A Convex deployment with `@convex-dev/workflow`, `@convex-dev/workpool`,
+  `@convex-dev/agent`, `@convex-dev/rate-limiter`, `@convex-dev/crons`, and
+  `@convex-dev/sharded-counter` resolvable (all installed automatically as
+  dependencies of this package).
+
+## License
+
+[FSL-1.1-Apache-2.0](./LICENSE) — free for production use; converts to
+Apache 2.0 after two years, per version.
+
+## Credit
+
+Slot names, contracts and authoring vocabulary are deliberately kept in
+parity with [vercel/eve](https://github.com/vercel/eve). This package is
+not affiliated with Vercel; parity is a design choice, not a claim of
+origin.