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

package/README.md

@@ -321,80 +321,96 @@ 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)
 
-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. T2-QUINQUIES widens this to the
-SESSIONS surface — EveVantage V4's conversation thread.
+`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`.
+- `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.
+- `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`: 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.
+- `component/lib/auth.ts` — `requireOrgId` / `assertSameOrg`: see "Trust
+  model" above.
 
-**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):
+**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):
 
 ```
-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.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({ name, instructions, model }) -> Id<"agents">
-components.agentEngine.engine.agents.get({ agentId }) -> agent | null
+components.agentEngine.engine.agents.create({ orgId, createdBy, name, instructions, model }) -> Id<"agents">
+components.agentEngine.engine.agents.get({ orgId, agentId }) -> agent | null
 
-components.agentEngine.engine.resolvers.resolveManifest({ sessionId }) -> { agentId, name, instructions, model, toolApprovals[] }
+components.agentEngine.engine.resolvers.resolveManifest({ orgId, 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.sessions.start({ orgId, agentId, createdBy }) -> Id<"sessions">
+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.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({ sessionId, toolName, approval: "always"|"once"|"never" }) -> null
+components.agentEngine.engine.toolApprovals.respond({ orgId, 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` +
+`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); (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.
+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` +

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

@@ -1,9 +1,12 @@
 export declare const create: import("convex/server").RegisteredMutation<"public", {
     name: string;
+    orgId: string;
     instructions: string;
     model: string;
+    createdBy: string;
 }, Promise<import("convex/values").GenericId<"agents">>>;
 export declare const get: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
     agentId: import("convex/values").GenericId<"agents">;
 }, Promise<{
     _id: import("convex/values").GenericId<"agents">;

package/dist/component/engine/agents.js

@@ -1,6 +1,6 @@
 import { v } from "convex/values";
-import { mutation, query } from "../_generated/server";
-import { requireOrgId } from "../lib/auth";
+import { mutation, query } from "../_generated/server.js";
+import { requireOrgId } from "../lib/auth.js";
 // 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
@@ -22,16 +22,18 @@ const agentDoc = v.object({
 });
 export const create = mutation({
     args: {
+        orgId: v.string(),
+        createdBy: v.string(),
         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");
+        const orgId = requireOrgId(args.orgId);
+        if (args.createdBy.trim().length === 0) {
+            throw new Error("Validation: createdBy must not be empty");
+        }
         if (args.name.trim().length === 0) {
             throw new Error("Validation: name must not be empty");
         }
@@ -48,17 +50,17 @@ export const create = mutation({
             instructions: args.instructions,
             model: args.model,
             status: "live",
-            createdBy: identity.subject,
+            createdBy: args.createdBy,
             createdAt: now,
             updatedAt: now,
         });
     },
 });
 export const get = query({
-    args: { agentId: v.id("agents") },
+    args: { orgId: v.string(), agentId: v.id("agents") },
     returns: v.union(agentDoc, v.null()),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         const doc = await ctx.db.get(args.agentId);
         if (!doc || doc.orgId !== orgId)
             return null;

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

@@ -1,12 +1,14 @@
 import { WorkflowManager, type WorkflowId } from "@convex-dev/workflow";
 export declare const workflow: WorkflowManager;
 export declare const start: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
     stepFunctionHandle: string;
     totalSteps: number;
     maxAttemptsPerStep: number;
     kind: string;
 }, Promise<import("convex/values").GenericId<"durableJobs">>>;
 export declare const getStatus: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
     jobId: import("convex/values").GenericId<"durableJobs">;
 }, Promise<{
     status: "running" | "completed" | "abandoned" | "cancelled";
@@ -16,6 +18,7 @@ export declare const getStatus: import("convex/server").RegisteredQuery<"public"
     abandonedAtStep: number | undefined;
 }>>;
 export declare const cancel: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
     jobId: import("convex/values").GenericId<"durableJobs">;
 }, Promise<null>>;
 export declare const getJobInternal: import("convex/server").RegisteredQuery<"internal", {

package/dist/component/engine/durableJob.js

@@ -1,8 +1,8 @@
 import { v } from "convex/values";
 import { WorkflowManager } from "@convex-dev/workflow";
-import { components, internal } from "../_generated/api";
-import { internalMutation, internalQuery, mutation, query, } from "../_generated/server";
-import { assertSameOrg, requireOrgId } from "../lib/auth";
+import { components, internal } from "../_generated/api.js";
+import { internalMutation, internalQuery, mutation, query, } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // durableJobs — THE SURVIVAL CONTRACT (I1, SYNTHESE.md §5/§7): "mise en
 // pause à la frontière d'étape, rejeu déterministe, reprise, abandon après
 // N échecs." This ENVELOPS `@convex-dev/workflow` -- it does not reimplement
@@ -50,6 +50,7 @@ export const workflow = new WorkflowManager(components.workflow);
 // ---------------------------------------------------------------------
 export const start = mutation({
     args: {
+        orgId: v.string(),
         kind: v.string(),
         stepFunctionHandle: v.string(),
         totalSteps: v.number(),
@@ -57,7 +58,7 @@ export const start = mutation({
     },
     returns: v.id("durableJobs"),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         if (!Number.isInteger(args.totalSteps) || args.totalSteps <= 0) {
             throw new Error("Validation: totalSteps must be a positive integer");
         }
@@ -87,7 +88,7 @@ export const start = mutation({
     },
 });
 export const getStatus = query({
-    args: { jobId: v.id("durableJobs") },
+    args: { orgId: v.string(), jobId: v.id("durableJobs") },
     returns: v.object({
         status: v.union(v.literal("running"), v.literal("completed"), v.literal("abandoned"), v.literal("cancelled")),
         cursor: v.number(),
@@ -96,7 +97,7 @@ export const getStatus = query({
         abandonedAtStep: v.optional(v.number()),
     }),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         const job = await ctx.db.get(args.jobId);
         assertSameOrg(orgId, job, "Job not found");
         return {
@@ -109,10 +110,10 @@ export const getStatus = query({
     },
 });
 export const cancel = mutation({
-    args: { jobId: v.id("durableJobs") },
+    args: { orgId: v.string(), jobId: v.id("durableJobs") },
     returns: v.null(),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         const job = await ctx.db.get(args.jobId);
         assertSameOrg(orgId, job, "Job not found");
         if (job.status !== "running")

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

@@ -1,4 +1,5 @@
 export declare const resolveManifest: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
     sessionId: import("convex/values").GenericId<"sessions">;
 }, Promise<{
     agentId: import("convex/values").GenericId<"agents">;

package/dist/component/engine/resolvers.js

@@ -1,6 +1,6 @@
 import { v } from "convex/values";
-import { query } from "../_generated/server";
-import { assertSameOrg, requireOrgId } from "../lib/auth";
+import { query } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // resolveManifest — the dynamic resolver (eve parity:
 // `dynamicInstructions`/`dynamicSkills`/`dynamicTools`,
 // packages/eve/src/compiler/manifest.ts:722-725). Produced FRESH from the
@@ -15,7 +15,7 @@ import { assertSameOrg, requireOrgId } from "../lib/auth";
 // component/schema.ts SCOPE note); this resolver returns only what the
 // component boundary currently owns.
 export const resolveManifest = query({
-    args: { sessionId: v.id("sessions") },
+    args: { orgId: v.string(), sessionId: v.id("sessions") },
     returns: v.object({
         agentId: v.id("agents"),
         name: v.string(),
@@ -27,7 +27,7 @@ export const resolveManifest = query({
         })),
     }),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         const session = await ctx.db.get(args.sessionId);
         assertSameOrg(orgId, session, "Session not found");
         const agent = await ctx.db.get(session.agentId);

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

@@ -1,15 +1,20 @@
 export declare const start: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    createdBy: string;
     agentId: import("convex/values").GenericId<"agents">;
 }, Promise<import("convex/values").GenericId<"sessions">>>;
 export declare const sendTurn: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
     sessionId: import("convex/values").GenericId<"sessions">;
     input: string;
 }, Promise<null>>;
 export declare const appendReasoning: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
     sessionId: import("convex/values").GenericId<"sessions">;
     chunk: string;
 }, Promise<null>>;
 export declare const requestToolCall: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
     toolName: string;
     sessionId: import("convex/values").GenericId<"sessions">;
     argsJson: string;
@@ -18,14 +23,17 @@ export declare const requestToolCall: import("convex/server").RegisteredMutation
     approvalPending: boolean;
 }>>;
 export declare const completeToolCall: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
     toolName: string;
     sessionId: import("convex/values").GenericId<"sessions">;
     resultJson: string;
 }, Promise<null>>;
 export declare const completeTurn: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
     sessionId: import("convex/values").GenericId<"sessions">;
 }, Promise<null>>;
 export declare const listEvents: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
     sessionId: import("convex/values").GenericId<"sessions">;
 }, Promise<{
     _id: import("convex/values").GenericId<"sessionEvents">;

package/dist/component/engine/sessions.js

@@ -1,7 +1,7 @@
 import { v } from "convex/values";
-import { api } from "../_generated/api";
-import { mutation, query } from "../_generated/server";
-import { assertSameOrg, requireOrgId } from "../lib/auth";
+import { api } from "../_generated/api.js";
+import { mutation, query } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // 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
@@ -26,13 +26,13 @@ async function insertEvent(ctx, args) {
 // 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") },
+    args: { orgId: v.string(), agentId: v.id("agents"), createdBy: v.string() },
     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 orgId = requireOrgId(args.orgId);
+        if (args.createdBy.trim().length === 0) {
+            throw new Error("Validation: createdBy must not be empty");
+        }
         const agent = await ctx.db.get(args.agentId);
         assertSameOrg(orgId, agent, "Agent not found");
         const now = Date.now();
@@ -40,12 +40,15 @@ export const start = mutation({
             orgId,
             agentId: args.agentId,
             status: "running",
-            createdBy: identity.subject,
+            createdBy: args.createdBy,
             createdAt: now,
             updatedAt: now,
         });
         await insertEvent(ctx, { orgId, sessionId, name: "session.started" });
-        await ctx.runQuery(api.engine.resolvers.resolveManifest, { sessionId });
+        await ctx.runQuery(api.engine.resolvers.resolveManifest, {
+            orgId,
+            sessionId,
+        });
         return sessionId;
     },
 });
@@ -55,10 +58,10 @@ export const start = mutation({
 // 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() },
+    args: { orgId: v.string(), sessionId: v.id("sessions"), input: v.string() },
     returns: v.null(),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         const session = await ctx.db.get(args.sessionId);
         assertSameOrg(orgId, session, "Session not found");
         if (session.status !== "running") {
@@ -71,6 +74,7 @@ export const sendTurn = mutation({
             payload: args.input,
         });
         await ctx.runQuery(api.engine.resolvers.resolveManifest, {
+            orgId,
             sessionId: args.sessionId,
         });
         await ctx.db.patch(args.sessionId, { updatedAt: Date.now() });
@@ -81,10 +85,10 @@ export const sendTurn = mutation({
 // 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() },
+    args: { orgId: v.string(), sessionId: v.id("sessions"), chunk: v.string() },
     returns: v.null(),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         const session = await ctx.db.get(args.sessionId);
         assertSameOrg(orgId, session, "Session not found");
         await insertEvent(ctx, {
@@ -103,13 +107,14 @@ export const appendReasoning = mutation({
 // `toolApprovals.respond`.
 export const requestToolCall = mutation({
     args: {
+        orgId: v.string(),
         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 orgId = requireOrgId(args.orgId);
         const session = await ctx.db.get(args.sessionId);
         assertSameOrg(orgId, session, "Session not found");
         await insertEvent(ctx, {
@@ -165,13 +170,14 @@ export const requestToolCall = mutation({
 // the gate).
 export const completeToolCall = mutation({
     args: {
+        orgId: v.string(),
         sessionId: v.id("sessions"),
         toolName: v.string(),
         resultJson: v.string(),
     },
     returns: v.null(),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         const session = await ctx.db.get(args.sessionId);
         assertSameOrg(orgId, session, "Session not found");
         await insertEvent(ctx, {
@@ -185,10 +191,10 @@ export const completeToolCall = mutation({
 });
 // completeTurn — closes the current turn.
 export const completeTurn = mutation({
-    args: { sessionId: v.id("sessions") },
+    args: { orgId: v.string(), sessionId: v.id("sessions") },
     returns: v.null(),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         const session = await ctx.db.get(args.sessionId);
         assertSameOrg(orgId, session, "Session not found");
         await insertEvent(ctx, {
@@ -204,7 +210,7 @@ export const completeTurn = mutation({
 // 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") },
+    args: { orgId: v.string(), sessionId: v.id("sessions") },
     returns: v.array(v.object({
         _id: v.id("sessionEvents"),
         _creationTime: v.number(),
@@ -213,7 +219,7 @@ export const listEvents = query({
         createdAt: v.number(),
     })),
     handler: async (ctx, args) => {
-        const orgId = await requireOrgId(ctx);
+        const orgId = requireOrgId(args.orgId);
         const session = await ctx.db.get(args.sessionId);
         assertSameOrg(orgId, session, "Session not found");
         const events = await ctx.db

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

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

package/dist/component/engine/toolApprovals.js

@@ -1,6 +1,6 @@
 import { v } from "convex/values";
-import { mutation } from "../_generated/server";
-import { assertSameOrg, requireOrgId } from "../lib/auth";
+import { mutation } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // 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
@@ -9,13 +9,14 @@ import { assertSameOrg, requireOrgId } from "../lib/auth";
 // "once" check (and any replaying client) can see it happened.
 export const respond = mutation({
     args: {
+        orgId: v.string(),
         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 orgId = requireOrgId(args.orgId);
         const session = await ctx.db.get(args.sessionId);
         assertSameOrg(orgId, session, "Session not found");
         const existing = await ctx.db

package/dist/component/lib/auth.d.ts

@@ -1,5 +1,4 @@
-import type { QueryCtx, MutationCtx } from "../_generated/server";
-export declare function requireOrgId(ctx: QueryCtx | MutationCtx): Promise<string>;
+export declare function requireOrgId(orgId: string | null | undefined): string;
 export declare function assertSameOrg(callerOrgId: string, doc: {
     orgId: string;
 } | null, notFoundMessage: string): asserts doc is {

package/dist/component/lib/auth.js

@@ -1,21 +1,34 @@
-// Deny by default. orgId is NEVER read from client args — it is derived
-// server-side from the authenticated identity (Clerk org claim). Every
-// mutation/query in this component must call this before touching data.
-export async function requireOrgId(ctx) {
-    const identity = await ctx.auth.getUserIdentity();
-    if (!identity) {
-        throw new Error("Unauthenticated: no identity on ctx.auth");
-    }
-    // Clerk org-scoped JWT template exposes `org_id` as a top-level claim.
-    const orgId = identity.org_id;
-    if (!orgId || typeof orgId !== "string" || orgId.length === 0) {
-        throw new Error("Unauthenticated: identity carries no org_id claim");
+// Trust model (CORRECTIF BLOQUANT, 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 component makes (convex-test: "Auth doesn't propagate across
+// component boundaries"). A handler inside this component can therefore
+// NEVER read `ctx.auth.getUserIdentity()` and expect it to reflect the
+// consumer app's end user -- there is no such identity to read here.
+//
+// The consumer app has ALREADY authenticated its user and resolved their
+// orgId on ITS OWN side (e.g. Clerk org claim, read in the consumer's own
+// `ctx.auth`) before ever calling into this component. `orgId` is passed
+// as an explicit argument on every public function in this component.
+//
+// What does NOT change: this component still derives NOTHING from the
+// client beyond what the consumer's public API surface exposes, still
+// denies by default, and `orgId` is still the first field of every index
+// and is still enforced on every document read via `assertSameOrg` below
+// -- a caller-supplied `orgId` can never see another org's rows. The
+// isolation boundary moved from "component reads ctx.auth" (impossible
+// across a component boundary) to "component enforces the orgId the
+// consumer already vouches for"; the boundary itself -- deny by default,
+// orgId first, no cross-org reads -- is unchanged.
+export function requireOrgId(orgId) {
+    if (!orgId || typeof orgId !== "string" || orgId.trim().length === 0) {
+        throw new Error("Unauthenticated: caller did not supply a non-empty orgId");
     }
     return orgId;
 }
-// Throws unless the document's orgId matches the caller's server-derived
-// orgId. Use on every read/write of a document fetched by _id, since
-// db.get() does not filter by index.
+// Throws unless the document's orgId matches the caller-supplied orgId.
+// Use on every read/write of a document fetched by _id, since db.get()
+// does not filter by index.
 export function assertSameOrg(callerOrgId, doc, notFoundMessage) {
     if (!doc || doc.orgId !== callerOrgId) {
         // Same error for "not found" and "cross-org" -- do not leak existence.

package/dist/component/testFixtures/callerSteps.js

@@ -1,5 +1,5 @@
 import { v } from "convex/values";
-import { internalMutation, internalQuery } from "../_generated/server";
+import { internalMutation, internalQuery } from "../_generated/server.js";
 // testFixtures/callerSteps — stand-ins for a CALLER'S OWN step function
 // (the thing a real consumer, e.g. VantagePeers, would define in ITS OWN
 // app and pass to `engine/durableJob.start` as `stepFunctionHandle` via

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/agent-engine",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "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",