@vantageos/agent-engine 0.1.0-alpha.5 → 0.1.0-alpha.7

package/README.md

@@ -1,337 +1,39 @@
 # @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, root-only `agent` tool | https://eve.dev/docs/subagents | `subagents` child table (`parentAgentId` -> `childAgentId`, recursive) | direct parity. **Isolation strict, "inherits nothing from the root's authored slots"** — a subagent row only declares the link + exposed tool name; it never inlines the parent's skills/connections/approvals |
-| `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 |
-| `subagents` used for inter-agent collaboration | eve docs | **not used** — collaboration goes through VantagePeers MCP tools instead | **notre ligne** — explicit Laurent decision (mvp-evevantage.md §2.5): "la collaboration entre agents n'arrive pas par les `subagents` d'eve" |
-| `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)
-
-Engine tables: `sessions`, `sessionEvents`, `awaitEventTimeouts`.
-
-**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.
-
-## `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:
-
-```
-git config core.hooksPath scripts/git-hooks
+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
 ```
 
-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.
-
-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:
+## Quickstart
+
+Register the component in your app's `convex/convex.config.ts`:
 
 ```ts
 import { defineApp } from "convex/server";
@@ -342,72 +44,47 @@ 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 a real slice of the engine, not just
-the component's identity:
-
-- `component/schema.ts` — `durableJobs`, `agents`, `toolApprovals`,
-  `sessions`, `sessionEvents` (+ a test-only `callerStepInvocations`
-  fixture table).
-- `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` (minimal root-sheet
-  bootstrap; no `update`/`list`/skills/connections in this pass).
-- `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`.
-- `component/engine/toolApprovals.ts` — `respond`.
-- `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, instructions, model }) -> Id<"agents">
+## What's inside
+
+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.
+
+### API surface (component/, current release)
+
+```
+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 }[]
+
 components.agentEngine.engine.resolvers.resolveManifest({ orgId, sessionId }) -> { agentId, name, instructions, model, toolApprovals[] }
 
-components.agentEngine.engine.sessions.start({ orgId, agentId, createdBy }) -> Id<"sessions">
+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 }
@@ -416,89 +93,93 @@ components.agentEngine.engine.sessions.completeTurn({ orgId, sessionId }) -> nul
 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.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.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.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" }
+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)
 ```
 
-### `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) `component/durableJob.componentPackaging.test.ts` +
-`component/sessions.componentPackaging.test.ts` run `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
-consumer probe (install the published tarball into a bare `npx convex dev`
-project, register the component, call `durableJob.start` + `sessions.start`
-from the consumer's own function, passing `orgId` explicitly) — see the
-completion report for the verbatim transcript.
-
-**NOT yet callable through the published component** (still only exists in
-this repo's OWN dev/test deployment under `convex/schema.ts` +
-`convex/agents.ts` + `convex/skills.ts`, used by `npx convex dev` and the
-repo-root `convex-test` suite): `skills`, `connections`, `subagents`,
-`habits`, `sandboxConfig`, `modelKeys`, `mandates`, `approvalRequests`,
-`awaitEventTimeouts`, `wakeableWork`, `engine/wakeup.ts`,
-`engine/workflows.ts` (`sessionWorkflowV1` — this pass's `sessions` is
-deliberately NOT tied to a `@convex-dev/workflow` run; see
-`component/schema.ts`'s `sessions` table comment for why). Porting each of
-those under `component/` without a working component-level `convex-test`
-harness behind it would ship unverified code — Day 128 forbids that; it is
-deliberately left for the next, separately-scoped migration.
-
-### 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) and T2-QUATER (this pass:
-migrated `durableJob` + its schema + `lib/auth.ts` under the actual
-component boundary, `component/`, with its own `_generated/` and its own
-green `convex-test` suite) — see "Packaging & publication" above; **not
-merged**.
+### 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.