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

package/README.md

@@ -37,12 +37,17 @@ ligne"** below, in this table and in the code comments next to the field.
 | `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 |
+| 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 |
-| `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" |
+| 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`)
@@ -59,8 +64,10 @@ Child tables (>= 7, every index starts with `orgId`):
 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`.
+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`
@@ -194,6 +201,64 @@ recurrence is a **dynamically registered `@convex-dev/crons` job**
   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)
+```
+
+`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
@@ -214,10 +279,31 @@ Two gates now exist, and they check different things:
    hand-edit of existing generated content.**
 2. **Content, requires a live deployment** --
    `scripts/check-generated-content.mjs` (`npm run
-   check:generated:content`). Actually runs `npx convex codegen` against
-   the dev deployment and diffs `convex/_generated/` byte-for-byte
-   (`git diff --exit-code`). Catches everything, including a single hand-
-   edited character.
+   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
@@ -299,6 +385,28 @@ that all contributors run) is Pi's to make, not this PR's.
   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`).
 
@@ -351,24 +459,56 @@ orgId-first-index, no-cross-org-reads are unchanged.
 
 `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:
+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` (+ a test-only `callerStepInvocations`
-  fixture table).
+  `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` (minimal root-sheet
-  bootstrap; no `update`/`list`/skills/connections in this pass).
+- `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`.
+  `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.
 
@@ -381,49 +521,141 @@ components.agentEngine.engine.durableJob.start({ orgId, kind, stepFunctionHandle
 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">
+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 }
+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, approval: "always"|"once"|"never" }) -> null
+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.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" }   (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()`)
 ```
 
+**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) `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.
+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/`
 
@@ -447,8 +679,15 @@ 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**.
+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.

package/dist/component/_generated/api.d.ts

@@ -7,21 +7,49 @@
  * @module
  */
 import type * as engine_agents from "../engine/agents.js";
+import type * as engine_awaitEventTimeout from "../engine/awaitEventTimeout.js";
+import type * as engine_delegation from "../engine/delegation.js";
+import type * as engine_directory from "../engine/directory.js";
 import type * as engine_durableJob from "../engine/durableJob.js";
+import type * as engine_habits from "../engine/habits.js";
+import type * as engine_mandates from "../engine/mandates.js";
 import type * as engine_resolvers from "../engine/resolvers.js";
+import type * as engine_sandboxCallback from "../engine/sandboxCallback.js";
 import type * as engine_sessions from "../engine/sessions.js";
 import type * as engine_toolApprovals from "../engine/toolApprovals.js";
+import type * as engine_vpConnection from "../engine/vpConnection.js";
+import type * as engine_wakeup from "../engine/wakeup.js";
+import type * as engine_workflows from "../engine/workflows.js";
 import type * as lib_auth from "../lib/auth.js";
 import type * as testFixtures_callerSteps from "../testFixtures/callerSteps.js";
+import type * as testFixtures_delegationDemoWorkflow from "../testFixtures/delegationDemoWorkflow.js";
+import type * as testFixtures_sandboxDemoWorkflow from "../testFixtures/sandboxDemoWorkflow.js";
+import type * as testFixtures_vpTool from "../testFixtures/vpTool.js";
+import type * as testFixtures_wakeupDemoWorkflow from "../testFixtures/wakeupDemoWorkflow.js";
+import type * as testFixtures_wakeupWork from "../testFixtures/wakeupWork.js";
 import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
 declare const fullApi: ApiFromModules<{
     "engine/agents": typeof engine_agents;
+    "engine/awaitEventTimeout": typeof engine_awaitEventTimeout;
+    "engine/delegation": typeof engine_delegation;
+    "engine/directory": typeof engine_directory;
     "engine/durableJob": typeof engine_durableJob;
+    "engine/habits": typeof engine_habits;
+    "engine/mandates": typeof engine_mandates;
     "engine/resolvers": typeof engine_resolvers;
+    "engine/sandboxCallback": typeof engine_sandboxCallback;
     "engine/sessions": typeof engine_sessions;
     "engine/toolApprovals": typeof engine_toolApprovals;
+    "engine/vpConnection": typeof engine_vpConnection;
+    "engine/wakeup": typeof engine_wakeup;
+    "engine/workflows": typeof engine_workflows;
     "lib/auth": typeof lib_auth;
     "testFixtures/callerSteps": typeof testFixtures_callerSteps;
+    "testFixtures/delegationDemoWorkflow": typeof testFixtures_delegationDemoWorkflow;
+    "testFixtures/sandboxDemoWorkflow": typeof testFixtures_sandboxDemoWorkflow;
+    "testFixtures/vpTool": typeof testFixtures_vpTool;
+    "testFixtures/wakeupDemoWorkflow": typeof testFixtures_wakeupDemoWorkflow;
+    "testFixtures/wakeupWork": typeof testFixtures_wakeupWork;
 }>;
 /**
  * A utility for referencing Convex functions in your app's public API.
@@ -46,5 +74,8 @@ export declare const components: {
     agentTurnPool: import("@convex-dev/workpool/_generated/component.js").ComponentApi<"agentTurnPool">;
     wakeupPool: import("@convex-dev/workpool/_generated/component.js").ComponentApi<"wakeupPool">;
     agent: import("@convex-dev/agent/_generated/component.js").ComponentApi<"agent">;
+    rateLimiter: import("@convex-dev/rate-limiter/_generated/component.js").ComponentApi<"rateLimiter">;
+    shardedCounter: import("@convex-dev/sharded-counter/_generated/component.js").ComponentApi<"shardedCounter">;
+    crons: import("@convex-dev/crons/_generated/component.js").ComponentApi<"crons">;
 };
 export {};