@vantageos/agent-engine 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -39,7 +39,8 @@ ligne"** below, in this table and in the code comments next to the field.
 | 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` child table (dynamic cron per agent/org, `@convex-dev/crons`) | **notre ligne (naming)** — Eve calls these schedules/hooks; we call them habits (product decision) and back them with runtime-registered crons instead of static config |
+| `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) |
@@ -53,10 +54,11 @@ 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` — dynamic crons (habits, notre ligne naming)
+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`.
 
@@ -126,6 +128,72 @@ reads without needing to know our internals):
   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
@@ -215,6 +283,17 @@ that all contributors run) is Pi's to make, not this PR's.
   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
@@ -247,42 +326,88 @@ export default app;
 Since T2-QUATER, `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` — the `durableJobs` table (+ 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.
+not just the component's identity. T2-QUINQUIES widens this to the
+SESSIONS surface — EveVantage V4's conversation thread.
+
+- `component/schema.ts` — `durableJobs`, `agents`, `toolApprovals`,
+  `sessions`, `sessionEvents` (+ a test-only `callerStepInvocations`
+  fixture table).
+- `component/engine/durableJob.ts` — `start` / `getStatus` / `cancel`.
+- `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.
+- `component/engine/toolApprovals.ts` — `respond`.
 - `component/lib/auth.ts` — `requireOrgId` / `assertSameOrg`: orgId is
   derived server-side and is the first field of every index; deny by
   default travels WITH the component, not just with this repo's own app.
 
-**Callable through the published component today:**
-`components.agentEngine.engine.durableJob.start(...)`,
-`.getStatus(...)`, `.cancel(...)` — verified two ways: (1)
-`component/durableJob.componentPackaging.test.ts` runs `convex-test`
-directly against `component/_generated/api` (the exact source tree
+**Callable through the published component today** (function signatures —
+all args/returns are explicit Convex validators, see the source files
+above for the exact `v.*` shapes):
+
+```
+components.agentEngine.engine.durableJob.start({ kind, stepFunctionHandle, totalSteps, maxAttemptsPerStep }) -> Id<"durableJobs">
+components.agentEngine.engine.durableJob.getStatus({ jobId }) -> { status, cursor, totalSteps, lastError?, abandonedAtStep? }
+components.agentEngine.engine.durableJob.cancel({ jobId }) -> null
+
+components.agentEngine.engine.agents.create({ name, instructions, model }) -> Id<"agents">
+components.agentEngine.engine.agents.get({ agentId }) -> agent | null
+
+components.agentEngine.engine.resolvers.resolveManifest({ sessionId }) -> { agentId, name, instructions, model, toolApprovals[] }
+
+components.agentEngine.engine.sessions.start({ agentId }) -> Id<"sessions">                          // session.started
+components.agentEngine.engine.sessions.sendTurn({ sessionId, input }) -> null                          // turn.started, rereads resolveManifest
+components.agentEngine.engine.sessions.appendReasoning({ sessionId, chunk }) -> null                   // streamed reasoning event
+components.agentEngine.engine.sessions.requestToolCall({ sessionId, toolName, argsJson }) -> { authorized, approvalPending }
+components.agentEngine.engine.sessions.completeToolCall({ sessionId, toolName, resultJson }) -> null
+components.agentEngine.engine.sessions.completeTurn({ sessionId }) -> null                             // turn.completed
+components.agentEngine.engine.sessions.listEvents({ sessionId }) -> sessionEvent[]                     // replay on reconnect (ordered by createdAt)
+
+components.agentEngine.engine.toolApprovals.respond({ sessionId, toolName, approval: "always"|"once"|"never" }) -> null
+```
+
+Streaming model: `sessionEvents` IS the transport. Convex query
+subscriptions on `sessions.listEvents` push every new row (reasoning
+chunk, tool-call lifecycle, approval lifecycle) to every subscriber live —
+there is no separate streaming channel to wire. A client that reconnects
+calls `listEvents` once to rebuild the whole thread, then keeps
+subscribing.
+
+Tool-approval gate (`toolApprovals.approval`, default `"never"`):
+`"never"` never pauses; `"always"` pauses (raises
+`tool.approval.requested`) on every `requestToolCall`; `"once"` pauses
+unless `tool.approval.resolved` for that tool was already recorded EARLIER
+IN THE SAME SESSION. `toolApprovals.respond` both writes the standing
+policy (upsert on `orgId`+`agentId`+`toolName`) and appends
+`tool.approval.resolved` for the calling session.
+
+Verified two ways, same discipline as T2-QUATER: (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` +
-`getStatus` from the consumer's own function) — see the T2-QUATER
-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` +
+what `npm pack` ships); (2) a from-scratch consumer probe (install the
+published tarball into a bare `npx convex dev` project, register the
+component, call `sessions.start`/`sendTurn` from the consumer's own
+function, confirm unauthenticated calls throw from the package's own
+`lib/auth`) — see the T2-QUINQUIES 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): the agent aggregate itself — `agents`,
-`skills`, `subagents`, `connections`, `habits`, `sandboxConfig`,
-`toolApprovals`, `modelKeys` — and the rest of the durable-session engine
-— `sessions`, `sessionEvents`, `awaitEventTimeouts`, `wakeableWork`,
-`engine/wakeup.ts`, `engine/resolvers.ts`, `engine/workflows.ts`
-(`sessionWorkflowV1`). 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.
+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/`
 
@@ -304,9 +429,10 @@ this exact repo layout, not guessed.
 
 T1 (schema + durable session engine, PR #1) merged @
 `9f3401ba63e6e663af95e9e4f5da42bc30b3550b`. I1 (long-task survival
-contract, `engine/durableJob.ts`) — 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**.
+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**.

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

@@ -6,12 +6,20 @@
  * To regenerate, run `npx convex dev`.
  * @module
  */
+import type * as engine_agents from "../engine/agents.js";
 import type * as engine_durableJob from "../engine/durableJob.js";
+import type * as engine_resolvers from "../engine/resolvers.js";
+import type * as engine_sessions from "../engine/sessions.js";
+import type * as engine_toolApprovals from "../engine/toolApprovals.js";
 import type * as lib_auth from "../lib/auth.js";
 import type * as testFixtures_callerSteps from "../testFixtures/callerSteps.js";
 import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
 declare const fullApi: ApiFromModules<{
+    "engine/agents": typeof engine_agents;
     "engine/durableJob": typeof engine_durableJob;
+    "engine/resolvers": typeof engine_resolvers;
+    "engine/sessions": typeof engine_sessions;
+    "engine/toolApprovals": typeof engine_toolApprovals;
     "lib/auth": typeof lib_auth;
     "testFixtures/callerSteps": typeof testFixtures_callerSteps;
 }>;

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

@@ -20,6 +20,27 @@ import type { FunctionReference } from "convex/server";
  */
 export type ComponentApi<Name extends string | undefined = string | undefined> = {
     engine: {
+        agents: {
+            create: FunctionReference<"mutation", "internal", {
+                instructions: string;
+                model: string;
+                name: string;
+            }, string, Name>;
+            get: FunctionReference<"query", "internal", {
+                agentId: string;
+            }, {
+                _creationTime: number;
+                _id: string;
+                createdAt: number;
+                createdBy: string;
+                instructions: string;
+                model: string;
+                name: string;
+                orgId: string;
+                status: "draft" | "live" | "archived";
+                updatedAt: number;
+            } | null, Name>;
+        };
         durableJob: {
             cancel: FunctionReference<"mutation", "internal", {
                 jobId: string;
@@ -40,5 +61,64 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 totalSteps: number;
             }, string, Name>;
         };
+        resolvers: {
+            resolveManifest: FunctionReference<"query", "internal", {
+                sessionId: string;
+            }, {
+                agentId: string;
+                instructions: string;
+                model: string;
+                name: string;
+                toolApprovals: Array<{
+                    approval: "always" | "once" | "never";
+                    toolName: string;
+                }>;
+            }, Name>;
+        };
+        sessions: {
+            appendReasoning: FunctionReference<"mutation", "internal", {
+                chunk: string;
+                sessionId: string;
+            }, null, Name>;
+            completeToolCall: FunctionReference<"mutation", "internal", {
+                resultJson: string;
+                sessionId: string;
+                toolName: string;
+            }, null, Name>;
+            completeTurn: FunctionReference<"mutation", "internal", {
+                sessionId: string;
+            }, null, Name>;
+            listEvents: FunctionReference<"query", "internal", {
+                sessionId: string;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                createdAt: number;
+                name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
+                payload?: string;
+            }>, Name>;
+            requestToolCall: FunctionReference<"mutation", "internal", {
+                argsJson: string;
+                sessionId: string;
+                toolName: string;
+            }, {
+                approvalPending: boolean;
+                authorized: boolean;
+            }, Name>;
+            sendTurn: FunctionReference<"mutation", "internal", {
+                input: string;
+                sessionId: string;
+            }, null, Name>;
+            start: FunctionReference<"mutation", "internal", {
+                agentId: string;
+            }, string, Name>;
+        };
+        toolApprovals: {
+            respond: FunctionReference<"mutation", "internal", {
+                approval: "always" | "once" | "never";
+                sessionId: string;
+                toolName: string;
+            }, null, Name>;
+        };
     };
 };

package/dist/component/engine/agents.d.ts

@@ -0,0 +1,19 @@
+export declare const create: import("convex/server").RegisteredMutation<"public", {
+    name: string;
+    instructions: string;
+    model: string;
+}, Promise<import("convex/values").GenericId<"agents">>>;
+export declare const get: import("convex/server").RegisteredQuery<"public", {
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"agents">;
+    _creationTime: number;
+    name: string;
+    orgId: string;
+    status: "draft" | "live" | "archived";
+    createdAt: number;
+    updatedAt: number;
+    instructions: string;
+    model: string;
+    createdBy: string;
+} | null>>;

package/dist/component/engine/agents.js

@@ -0,0 +1,67 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+import { requireOrgId } from "../lib/auth";
+// engine/agents — MINIMAL root-sheet bootstrap for the sessions surface
+// (T2-QUINQUIES). `sessions.start` needs an `agentId` it can read INSIDE
+// the component boundary (component isolation: it cannot reach into a
+// consumer app's own `agents` table). This is deliberately narrow: only
+// `create`/`get`, no `update`/`list`/skills/connections — the full agent
+// aggregate CRUD stays out of this component boundary for this pass (see
+// component/schema.ts SCOPE note).
+const agentDoc = v.object({
+    _id: v.id("agents"),
+    _creationTime: v.number(),
+    orgId: v.string(),
+    name: v.string(),
+    instructions: v.string(),
+    model: v.string(),
+    status: v.union(v.literal("draft"), v.literal("live"), v.literal("archived")),
+    createdBy: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+export const create = mutation({
+    args: {
+        name: v.string(),
+        instructions: v.string(),
+        model: v.string(),
+    },
+    returns: v.id("agents"),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const identity = await ctx.auth.getUserIdentity();
+        if (!identity)
+            throw new Error("Unauthenticated");
+        if (args.name.trim().length === 0) {
+            throw new Error("Validation: name must not be empty");
+        }
+        if (args.instructions.trim().length === 0) {
+            throw new Error("Validation: instructions must not be empty");
+        }
+        if (args.model.trim().length === 0) {
+            throw new Error("Validation: model must not be empty");
+        }
+        const now = Date.now();
+        return await ctx.db.insert("agents", {
+            orgId,
+            name: args.name,
+            instructions: args.instructions,
+            model: args.model,
+            status: "live",
+            createdBy: identity.subject,
+            createdAt: now,
+            updatedAt: now,
+        });
+    },
+});
+export const get = query({
+    args: { agentId: v.id("agents") },
+    returns: v.union(agentDoc, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const doc = await ctx.db.get(args.agentId);
+        if (!doc || doc.orgId !== orgId)
+            return null;
+        return doc;
+    },
+});

package/dist/component/engine/resolvers.d.ts

@@ -0,0 +1,12 @@
+export declare const resolveManifest: import("convex/server").RegisteredQuery<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+}, Promise<{
+    agentId: import("convex/values").GenericId<"agents">;
+    name: string;
+    instructions: string;
+    model: string;
+    toolApprovals: {
+        toolName: string;
+        approval: "always" | "once" | "never";
+    }[];
+}>>;

package/dist/component/engine/resolvers.js

@@ -0,0 +1,50 @@
+import { v } from "convex/values";
+import { query } from "../_generated/server";
+import { assertSameOrg, requireOrgId } from "../lib/auth";
+// resolveManifest — the dynamic resolver (eve parity:
+// `dynamicInstructions`/`dynamicSkills`/`dynamicTools`,
+// packages/eve/src/compiler/manifest.ts:722-725). Produced FRESH from the
+// aggregate on every call, never compiled/cached — an agent edited between
+// sessions is visible on the very next `session.started`/`turn.started`
+// call with zero redeploy. `sessions.start` and `sessions.sendTurn` both
+// call this at their respective boundaries (ALLOWED_DYNAMIC_INSTRUCTION_
+// EVENTS, dynamic-tool-definition.ts:40-46).
+//
+// T2-QUINQUIES scope note: `toolApprovals` is included (in scope per
+// brief). `skills`/`connections` are NOT (out of scope for this pass — see
+// component/schema.ts SCOPE note); this resolver returns only what the
+// component boundary currently owns.
+export const resolveManifest = query({
+    args: { sessionId: v.id("sessions") },
+    returns: v.object({
+        agentId: v.id("agents"),
+        name: v.string(),
+        instructions: v.string(),
+        model: v.string(),
+        toolApprovals: v.array(v.object({
+            toolName: v.string(),
+            approval: v.union(v.literal("always"), v.literal("once"), v.literal("never")),
+        })),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        const agent = await ctx.db.get(session.agentId);
+        assertSameOrg(orgId, agent, "Agent not found");
+        const toolApprovals = await ctx.db
+            .query("toolApprovals")
+            .withIndex("by_org_agent", (q) => q.eq("orgId", orgId).eq("agentId", session.agentId))
+            .collect();
+        return {
+            agentId: agent._id,
+            name: agent.name,
+            instructions: agent.instructions,
+            model: agent.model,
+            toolApprovals: toolApprovals.map((t) => ({
+                toolName: t.toolName,
+                approval: t.approval,
+            })),
+        };
+    },
+});

package/dist/component/engine/sessions.d.ts

@@ -0,0 +1,36 @@
+export declare const start: import("convex/server").RegisteredMutation<"public", {
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<import("convex/values").GenericId<"sessions">>>;
+export declare const sendTurn: import("convex/server").RegisteredMutation<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+    input: string;
+}, Promise<null>>;
+export declare const appendReasoning: import("convex/server").RegisteredMutation<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+    chunk: string;
+}, Promise<null>>;
+export declare const requestToolCall: import("convex/server").RegisteredMutation<"public", {
+    toolName: string;
+    sessionId: import("convex/values").GenericId<"sessions">;
+    argsJson: string;
+}, Promise<{
+    authorized: boolean;
+    approvalPending: boolean;
+}>>;
+export declare const completeToolCall: import("convex/server").RegisteredMutation<"public", {
+    toolName: string;
+    sessionId: import("convex/values").GenericId<"sessions">;
+    resultJson: string;
+}, Promise<null>>;
+export declare const completeTurn: import("convex/server").RegisteredMutation<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+}, Promise<null>>;
+export declare const listEvents: import("convex/server").RegisteredQuery<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"sessionEvents">;
+    _creationTime: number;
+    name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
+    payload: string | undefined;
+    createdAt: number;
+}[]>>;

package/dist/component/engine/sessions.js

@@ -0,0 +1,233 @@
+import { v } from "convex/values";
+import { api } from "../_generated/api";
+import { mutation, query } from "../_generated/server";
+import { assertSameOrg, requireOrgId } from "../lib/auth";
+// engine/sessions — THE FIL DE CONVERSATION contract (T2-QUINQUIES). This
+// is what unblocks EveVantage V4: open a session, send a turn, stream
+// reasoning/tool calls, gate on tool approval, replay the thread on
+// reconnect. See component/schema.ts for the event log this is built on
+// (`sessionEvents` IS the streaming transport via Convex reactivity — no
+// separate channel).
+//
+// Named events mirror eve's session/turn boundaries
+// (dynamic-tool-definition.ts:40-46): `session.started`, `turn.started`.
+// `resolvers.resolveManifest` (engine/resolvers.ts) is reread at BOTH of
+// those boundaries — never mid-turn — so an agent edit is visible at the
+// very next turn with zero redeploy.
+async function insertEvent(ctx, args) {
+    await ctx.db.insert("sessionEvents", {
+        orgId: args.orgId,
+        sessionId: args.sessionId,
+        name: args.name,
+        payload: args.payload,
+        createdAt: Date.now(),
+    });
+}
+// start — opens a session (session.started boundary), rereading the
+// manifest immediately so a caller can act on it before the first turn.
+export const start = mutation({
+    args: { agentId: v.id("agents") },
+    returns: v.id("sessions"),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const identity = await ctx.auth.getUserIdentity();
+        if (!identity)
+            throw new Error("Unauthenticated");
+        const agent = await ctx.db.get(args.agentId);
+        assertSameOrg(orgId, agent, "Agent not found");
+        const now = Date.now();
+        const sessionId = await ctx.db.insert("sessions", {
+            orgId,
+            agentId: args.agentId,
+            status: "running",
+            createdBy: identity.subject,
+            createdAt: now,
+            updatedAt: now,
+        });
+        await insertEvent(ctx, { orgId, sessionId, name: "session.started" });
+        await ctx.runQuery(api.engine.resolvers.resolveManifest, { sessionId });
+        return sessionId;
+    },
+});
+// sendTurn — turn.started boundary. Rereads the manifest (eve parity: dynamic
+// resolvers only allowed to reread at session.started/turn.started).
+// `input` is the caller-owned turn payload (already-serialized JSON/text);
+// this component does not interpret it -- it is stored verbatim as the
+// event payload for replay.
+export const sendTurn = mutation({
+    args: { sessionId: v.id("sessions"), input: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        if (session.status !== "running") {
+            throw new Error(`Session is not running (status=${session.status})`);
+        }
+        await insertEvent(ctx, {
+            orgId,
+            sessionId: args.sessionId,
+            name: "turn.started",
+            payload: args.input,
+        });
+        await ctx.runQuery(api.engine.resolvers.resolveManifest, {
+            sessionId: args.sessionId,
+        });
+        await ctx.db.patch(args.sessionId, { updatedAt: Date.now() });
+        return null;
+    },
+});
+// appendReasoning — one streamed reasoning chunk. Convex query reactivity
+// on `listEvents` is the streaming transport: each insert here is pushed to
+// every subscriber live, no separate channel needed.
+export const appendReasoning = mutation({
+    args: { sessionId: v.id("sessions"), chunk: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        await insertEvent(ctx, {
+            orgId,
+            sessionId: args.sessionId,
+            name: "turn.reasoning",
+            payload: args.chunk,
+        });
+        return null;
+    },
+});
+// requestToolCall — gates on the agent's toolApprovals row for `toolName`
+// (default "never" = no gate). "always" gates every call; "once" gates
+// unless already resolved earlier in THIS session. Returns whether the
+// caller may proceed immediately or must wait for
+// `toolApprovals.respond`.
+export const requestToolCall = mutation({
+    args: {
+        sessionId: v.id("sessions"),
+        toolName: v.string(),
+        argsJson: v.string(),
+    },
+    returns: v.object({ authorized: v.boolean(), approvalPending: v.boolean() }),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        await insertEvent(ctx, {
+            orgId,
+            sessionId: args.sessionId,
+            name: "turn.toolCall.requested",
+            payload: JSON.stringify({ toolName: args.toolName, args: args.argsJson }),
+        });
+        const approvalRow = await ctx.db
+            .query("toolApprovals")
+            .withIndex("by_org_agent_tool", (q) => q
+            .eq("orgId", orgId)
+            .eq("agentId", session.agentId)
+            .eq("toolName", args.toolName))
+            .unique();
+        const approval = approvalRow?.approval ?? "never";
+        if (approval === "never") {
+            return { authorized: true, approvalPending: false };
+        }
+        if (approval === "always") {
+            await insertEvent(ctx, {
+                orgId,
+                sessionId: args.sessionId,
+                name: "tool.approval.requested",
+                payload: JSON.stringify({ toolName: args.toolName }),
+            });
+            return { authorized: false, approvalPending: true };
+        }
+        // approval === "once": gate unless this tool was already resolved once
+        // in this session.
+        const events = await ctx.db
+            .query("sessionEvents")
+            .withIndex("by_org_session", (q) => q.eq("orgId", orgId).eq("sessionId", args.sessionId))
+            .collect();
+        const alreadyResolvedThisSession = events.some((e) => e.name === "tool.approval.resolved" &&
+            e.payload !== undefined &&
+            JSON.parse(e.payload).toolName ===
+                args.toolName);
+        if (alreadyResolvedThisSession) {
+            return { authorized: true, approvalPending: false };
+        }
+        await insertEvent(ctx, {
+            orgId,
+            sessionId: args.sessionId,
+            name: "tool.approval.requested",
+            payload: JSON.stringify({ toolName: args.toolName }),
+        });
+        return { authorized: false, approvalPending: true };
+    },
+});
+// completeToolCall — the caller invokes this after actually running the
+// tool (authorized immediately, or after `toolApprovals.respond` cleared
+// the gate).
+export const completeToolCall = mutation({
+    args: {
+        sessionId: v.id("sessions"),
+        toolName: v.string(),
+        resultJson: v.string(),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        await insertEvent(ctx, {
+            orgId,
+            sessionId: args.sessionId,
+            name: "turn.toolCall.completed",
+            payload: JSON.stringify({ toolName: args.toolName, result: args.resultJson }),
+        });
+        return null;
+    },
+});
+// completeTurn — closes the current turn.
+export const completeTurn = mutation({
+    args: { sessionId: v.id("sessions") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        await insertEvent(ctx, {
+            orgId,
+            sessionId: args.sessionId,
+            name: "turn.completed",
+        });
+        await ctx.db.patch(args.sessionId, { updatedAt: Date.now() });
+        return null;
+    },
+});
+// listEvents — REPLAY ON RECONNECT: the full ordered event log for a
+// session. A client that drops and reconnects calls this once to rebuild
+// the thread, then subscribes (Convex reactivity) for anything after.
+export const listEvents = query({
+    args: { sessionId: v.id("sessions") },
+    returns: v.array(v.object({
+        _id: v.id("sessionEvents"),
+        _creationTime: v.number(),
+        name: v.union(v.literal("session.started"), v.literal("turn.started"), v.literal("turn.reasoning"), v.literal("turn.toolCall.requested"), v.literal("turn.toolCall.completed"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved")),
+        payload: v.optional(v.string()),
+        createdAt: v.number(),
+    })),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        const events = await ctx.db
+            .query("sessionEvents")
+            .withIndex("by_org_session", (q) => q.eq("orgId", orgId).eq("sessionId", args.sessionId))
+            .collect();
+        return events
+            .sort((a, b) => a.createdAt - b.createdAt)
+            .map((e) => ({
+            _id: e._id,
+            _creationTime: e._creationTime,
+            name: e.name,
+            payload: e.payload,
+            createdAt: e.createdAt,
+        }));
+    },
+});

package/dist/component/engine/toolApprovals.d.ts

@@ -0,0 +1,5 @@
+export declare const respond: import("convex/server").RegisteredMutation<"public", {
+    toolName: string;
+    approval: "always" | "once" | "never";
+    sessionId: import("convex/values").GenericId<"sessions">;
+}, Promise<null>>;

package/dist/component/engine/toolApprovals.js

@@ -0,0 +1,51 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server";
+import { assertSameOrg, requireOrgId } from "../lib/auth";
+// engine/toolApprovals — respond to a pending approval request
+// (`tool.approval.requested`, raised by `sessions.requestToolCall`). The
+// decision (always/once/never) is WRITTEN as the agent's standing policy
+// for that tool going forward (upsert on `by_org_agent_tool`), and
+// `tool.approval.resolved` is appended so `sessions.requestToolCall`'s
+// "once" check (and any replaying client) can see it happened.
+export const respond = mutation({
+    args: {
+        sessionId: v.id("sessions"),
+        toolName: v.string(),
+        approval: v.union(v.literal("always"), v.literal("once"), v.literal("never")),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        const existing = await ctx.db
+            .query("toolApprovals")
+            .withIndex("by_org_agent_tool", (q) => q
+            .eq("orgId", orgId)
+            .eq("agentId", session.agentId)
+            .eq("toolName", args.toolName))
+            .unique();
+        const now = Date.now();
+        if (existing) {
+            await ctx.db.patch(existing._id, { approval: args.approval, updatedAt: now });
+        }
+        else {
+            await ctx.db.insert("toolApprovals", {
+                orgId,
+                agentId: session.agentId,
+                toolName: args.toolName,
+                approval: args.approval,
+                createdAt: now,
+                updatedAt: now,
+            });
+        }
+        await ctx.db.insert("sessionEvents", {
+            orgId,
+            sessionId: args.sessionId,
+            name: "tool.approval.resolved",
+            payload: JSON.stringify({ toolName: args.toolName, approval: args.approval }),
+            createdAt: now,
+        });
+        return null;
+    },
+});

package/dist/component/schema.d.ts

@@ -45,5 +45,80 @@ declare const _default: import("convex/server").SchemaDefinition<{
         by_org: ["orgId", "_creationTime"];
         by_org_job: ["orgId", "jobId", "_creationTime"];
     }, {}, {}>;
+    agents: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        name: string;
+        orgId: string;
+        status: "draft" | "live" | "archived";
+        createdAt: number;
+        updatedAt: number;
+        instructions: string;
+        model: string;
+        createdBy: string;
+    }, {
+        orgId: import("convex/values").VString<string, "required">;
+        name: import("convex/values").VString<string, "required">;
+        instructions: import("convex/values").VString<string, "required">;
+        model: import("convex/values").VString<string, "required">;
+        status: import("convex/values").VUnion<"draft" | "live" | "archived", [import("convex/values").VLiteral<"draft", "required">, import("convex/values").VLiteral<"live", "required">, import("convex/values").VLiteral<"archived", "required">], "required", never>;
+        createdBy: import("convex/values").VString<string, "required">;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+        updatedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "name" | "orgId" | "status" | "createdAt" | "updatedAt" | "instructions" | "model" | "createdBy">, {
+        by_org: ["orgId", "_creationTime"];
+        by_org_status: ["orgId", "status", "_creationTime"];
+    }, {}, {}>;
+    toolApprovals: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        orgId: string;
+        createdAt: number;
+        updatedAt: number;
+        agentId: import("convex/values").GenericId<"agents">;
+        toolName: string;
+        approval: "always" | "once" | "never";
+    }, {
+        orgId: import("convex/values").VString<string, "required">;
+        agentId: import("convex/values").VId<import("convex/values").GenericId<"agents">, "required">;
+        toolName: import("convex/values").VString<string, "required">;
+        approval: import("convex/values").VUnion<"always" | "once" | "never", [import("convex/values").VLiteral<"always", "required">, import("convex/values").VLiteral<"once", "required">, import("convex/values").VLiteral<"never", "required">], "required", never>;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+        updatedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "orgId" | "createdAt" | "updatedAt" | "agentId" | "toolName" | "approval">, {
+        by_org: ["orgId", "_creationTime"];
+        by_org_agent: ["orgId", "agentId", "_creationTime"];
+        by_org_agent_tool: ["orgId", "agentId", "toolName", "_creationTime"];
+    }, {}, {}>;
+    sessions: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        orgId: string;
+        status: "running" | "completed" | "cancelled";
+        createdAt: number;
+        updatedAt: number;
+        createdBy: string;
+        agentId: import("convex/values").GenericId<"agents">;
+    }, {
+        orgId: import("convex/values").VString<string, "required">;
+        agentId: import("convex/values").VId<import("convex/values").GenericId<"agents">, "required">;
+        status: import("convex/values").VUnion<"running" | "completed" | "cancelled", [import("convex/values").VLiteral<"running", "required">, import("convex/values").VLiteral<"completed", "required">, import("convex/values").VLiteral<"cancelled", "required">], "required", never>;
+        createdBy: import("convex/values").VString<string, "required">;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+        updatedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "orgId" | "status" | "createdAt" | "updatedAt" | "createdBy" | "agentId">, {
+        by_org: ["orgId", "_creationTime"];
+        by_org_agent: ["orgId", "agentId", "_creationTime"];
+    }, {}, {}>;
+    sessionEvents: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        payload?: string | undefined;
+        name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
+        orgId: string;
+        createdAt: number;
+        sessionId: import("convex/values").GenericId<"sessions">;
+    }, {
+        orgId: import("convex/values").VString<string, "required">;
+        sessionId: import("convex/values").VId<import("convex/values").GenericId<"sessions">, "required">;
+        name: import("convex/values").VUnion<"session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved", [import("convex/values").VLiteral<"session.started", "required">, import("convex/values").VLiteral<"turn.started", "required">, import("convex/values").VLiteral<"turn.reasoning", "required">, import("convex/values").VLiteral<"turn.toolCall.requested", "required">, import("convex/values").VLiteral<"turn.toolCall.completed", "required">, import("convex/values").VLiteral<"turn.completed", "required">, import("convex/values").VLiteral<"tool.approval.requested", "required">, import("convex/values").VLiteral<"tool.approval.resolved", "required">], "required", never>;
+        payload: import("convex/values").VString<string | undefined, "optional">;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "name" | "orgId" | "createdAt" | "sessionId" | "payload">, {
+        by_org: ["orgId", "_creationTime"];
+        by_org_session: ["orgId", "sessionId", "_creationTime"];
+    }, {}, {}>;
 }, true>;
 export default _default;

package/dist/component/schema.js

@@ -7,17 +7,18 @@ import { v } from "convex/values";
 // `app.use(agentEngine)` — as opposed to `convex/schema.ts` at the repo
 // root, which only backs THIS repo's own dev/test deployment.
 //
-// SCOPE (T2-QUATER, deliberately narrow — see README "What's callable"):
-// only the tables `engine/durableJob.ts` requires. The full agent
-// aggregate (agents, skills, subagents, connections, habits,
-// sandboxConfig, toolApprovals, modelKeys, sessions, sessionEvents,
-// awaitEventTimeouts, wakeableWork, wakeupDemoResults) is NOT yet
-// re-hosted under this component boundary — that is the next, separately
-// scoped migration. Porting the durableJob engine first unblocks
-// VantagePeers/Sigma's I1 need (durable long-task survival) without
-// widening the surface being shipped-and-verified beyond what has an
-// actual working component-level test harness behind it (Day 128: never
-// ship unverified).
+// SCOPE (T2-QUATER: durableJob only. T2-QUINQUIES, this pass: WIDENS the
+// boundary to the SESSIONS surface Hestia's EveVantage V4 conversation
+// thread needs — session start/turn, streamed reasoning/tool-call events,
+// toolApprovals response, replay on reconnect, dynamic resolver — see
+// README "What's callable"). Still DELIBERATELY NARROW: `skills`,
+// `connections`, `subagents`, `habits`, `sandboxConfig`, `modelKeys`,
+// `mandates`, `awaitEventTimeouts`, `wakeableWork` are NOT re-hosted here —
+// each of those needs its own component-level test harness first (Day 128:
+// never ship unverified). `agents` is included, minimally, because a
+// session cannot exist without an owning agent row the component itself
+// can read (component isolation: this package cannot read a consumer app's
+// OWN `agents` table across the component boundary).
 export default defineSchema({
     // durableJobs — GENERIC durable step-batch primitive (I1, SYNTHESE.md
     // §5/§7). See convex/engine/durableJob.ts (repo root) for the full
@@ -53,4 +54,77 @@ export default defineSchema({
     })
         .index("by_org", ["orgId"])
         .index("by_org_job", ["orgId", "jobId"]),
+    // ---------------------------------------------------------------------
+    // T2-QUINQUIES — SESSIONS surface (EveVantage V4 conversation thread).
+    // ---------------------------------------------------------------------
+    // agents — minimal root sheet, ONLY the fields the sessions surface
+    // needs to resolve a manifest (name/instructions/model) + gate tool
+    // calls (via toolApprovals below). The full agent aggregate (skills,
+    // connections, subagents, habits, sandboxConfig, modelKeys) stays out of
+    // this component boundary for this pass — see the SCOPE note above.
+    agents: defineTable({
+        orgId: v.string(),
+        name: v.string(),
+        instructions: v.string(),
+        model: v.string(),
+        status: v.union(v.literal("draft"), v.literal("live"), v.literal("archived")),
+        createdBy: v.string(),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_status", ["orgId", "status"]),
+    // toolApprovals — approval gate per (agent, tool), eve parity
+    // (public/definitions/tool.ts:117-125). "never" (default) means a tool
+    // call never pauses for human approval; "always"/"once" gate every /
+    // first call of a session via a `tool.approval.requested` sessionEvent
+    // that `toolApprovals.respond` resolves.
+    toolApprovals: defineTable({
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        toolName: v.string(),
+        approval: v.union(v.literal("always"), v.literal("once"), v.literal("never")),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_agent", ["orgId", "agentId"])
+        .index("by_org_agent_tool", ["orgId", "agentId", "toolName"]),
+    // sessions — one conversation container per `sessions.start` call. This
+    // pass deliberately does NOT tie a session to a `@convex-dev/workflow`
+    // run (unlike the repo-root, app-level `convex/engine/sessions.ts`
+    // prototype this was ported from) — long-task durability is already
+    // covered by `engine/durableJob.ts`; a consumer that needs a durable
+    // workflow driving turns can wire one on top using `durableJob.start`
+    // with its own step function. This is a deliberate divergence ("notre
+    // ligne") from the app-level prototype, narrowing the shipped surface to
+    // what has a working component-level test harness behind it.
+    sessions: defineTable({
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        status: v.union(v.literal("running"), v.literal("completed"), v.literal("cancelled")),
+        createdBy: v.string(),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_agent", ["orgId", "agentId"]),
+    // sessionEvents — the append-only event log a client replays on
+    // reconnect (`sessions.listEvents`) and that IS the streaming transport:
+    // Convex query subscriptions push new rows to every subscriber in real
+    // time, so "streaming the reasoning and tool calls" is simply inserting
+    // rows here as they happen and letting reactivity carry them to the
+    // client — no separate transport needed. Event names mirror eve's
+    // session/turn boundaries (`session.started`, `turn.started`,
+    // dynamic-tool-definition.ts:40-46) plus the turn-body events this pass
+    // adds (reasoning chunks, tool-call lifecycle, approval lifecycle).
+    sessionEvents: defineTable({
+        orgId: v.string(),
+        sessionId: v.id("sessions"),
+        name: v.union(v.literal("session.started"), v.literal("turn.started"), v.literal("turn.reasoning"), v.literal("turn.toolCall.requested"), v.literal("turn.toolCall.completed"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved")),
+        payload: v.optional(v.string()), // JSON-serialized, free contract per event name
+        createdAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_session", ["orgId", "sessionId"]),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/agent-engine",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "Reusable Convex component: durable agent engine. Agent = data aggregate (root sheet + child tables), never compiled code. Built on @convex-dev/workflow + @convex-dev/workpool (+ @convex-dev/agent). Eve parity by design.",
   "type": "module",
   "license": "UNLICENSED",
@@ -38,6 +38,10 @@
   },
   "dependencies": {
     "@convex-dev/agent": "0.6.4",
+    "@convex-dev/aggregate": "^0.2.2",
+    "@convex-dev/crons": "^0.2.2",
+    "@convex-dev/rate-limiter": "^0.3.2",
+    "@convex-dev/sharded-counter": "^0.2.1",
     "@convex-dev/workflow": "0.4.4",
     "@convex-dev/workpool": "0.4.7",
     "ai": "6.0.35",