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

package/dist/component/engine/sandboxCallback.js

@@ -0,0 +1,259 @@
+import { WorkflowManager } from "@convex-dev/workflow";
+import { v } from "convex/values";
+import { components, internal } from "../_generated/api.js";
+import { internalMutation, mutation, query } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
+// engine/sandboxCallback — THE SIGNED CALLBACK GATE'S DB-SIDE LOGIC.
+//
+// BOUNDARY (see the sandbox-bridge header in component/schema.ts for the
+// measured verdict behind each of these):
+//   - The public HTTP route (`/sandbox/callback`) that verifies the
+//     `SANDBOX_CALLBACK_SECRET` HMAC signature over the raw body CANNOT
+//     live in this component (no official `@convex-dev/*` component ships
+//     an `http.ts`, and none reads `process.env` directly). It stays in
+//     the consumer app's `convex/http.ts`, which reads the secret, verifies
+//     the signature, and ONLY THEN calls `processCallback` /
+//     `deadLetterMalformed` below.
+//   - The "use node" action that talks to `@vercel/sandbox`
+//     (`Sandbox.create()` / `sandbox.runCommand()`) CANNOT live in this
+//     component either (Convex's own bundler hard-crashes on any "use
+//     node" file inside a child component). It stays app-level
+//     and calls INTO `startRun` / `attachSandboxId` below (both PUBLIC
+//     `mutation`s, not `internalMutation`s, precisely so a cross-component
+//     caller can reach them — a component's `internal*` functions are
+//     unreachable from outside the component; engine/mandates.ts's
+//     `spendInternal` follows the same convention).
+//
+// Everything below assumes the signature already checked out (verified by
+// the caller, upstream of this module) — this module's job is dedup-by-
+// delivery-id + the actual wake, both inside ONE mutation transaction so a
+// replayed delivery can never cause a second `sendEvent`. `orgId` is an
+// explicit ARGUMENT on every public function (component boundaries do not
+// propagate `ctx.auth`, see component/lib/auth.ts).
+//
+// Same WorkflowManager component as engine/wakeup.ts / engine/workflows.ts.
+const workflow = new WorkflowManager(components.workflow);
+const wakeStatus = v.union(v.literal("completed"), v.literal("failed"));
+// startRun — the DB-side half of launching a sandbox run (called by the
+// app-level "use node" action, convex/engine/sandboxBridgeActions.ts,
+// AFTER `engine.mandates.spend` has funded it, same two-transaction
+// protocol as `engine.wakeup.enqueue`). Returns the row id so the caller
+// can inject it into the sandbox's own env (SANDBOX_RUN_ID) before
+// `Sandbox.create()`, and schedules the self-built awaitEvent timeout
+// (workflow#177 pattern, same discipline as engine/awaitEventTimeout.ts)
+// so a sandbox that never calls back — killed by the platform's own
+// ceiling, crashed, or just lost — still wakes the workflow, in FAILURE,
+// rather than leaving it asleep forever.
+export const startRun = mutation({
+    args: {
+        orgId: v.string(),
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+        timeoutMs: v.number(),
+    },
+    returns: v.id("sandboxRuns"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        if (args.workflowId.length === 0) {
+            throw new Error("Validation: workflowId must not be empty");
+        }
+        if (args.awaitedEventName.length === 0) {
+            throw new Error("Validation: awaitedEventName must not be empty");
+        }
+        if (args.timeoutMs <= 0) {
+            throw new Error("Validation: timeoutMs must be > 0");
+        }
+        const now = Date.now();
+        const runId = await ctx.db.insert("sandboxRuns", {
+            orgId,
+            workflowId: args.workflowId,
+            awaitedEventName: args.awaitedEventName,
+            sandboxId: "", // patched by attachSandboxId once Sandbox.create() resolves
+            status: "pending",
+            createdAt: now,
+            updatedAt: now,
+        });
+        await ctx.scheduler.runAfter(args.timeoutMs, internal.engine.sandboxCallback.timeoutInternal, {
+            sandboxRunId: runId,
+        });
+        return runId;
+    },
+});
+// attachSandboxId — patches the Vercel-assigned sandbox id onto the row
+// once `Sandbox.create()` returns it. Separate step because the row must
+// exist BEFORE the sandbox is created (its id is one of the sandbox's own
+// env vars, so the sandbox can name itself in its callback payload).
+export const attachSandboxId = mutation({
+    args: { orgId: v.string(), sandboxRunId: v.id("sandboxRuns"), sandboxId: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const run = await ctx.db.get(args.sandboxRunId);
+        assertSameOrg(orgId, run, "Sandbox run not found");
+        if (args.sandboxId.length === 0) {
+            throw new Error("Validation: sandboxId must not be empty");
+        }
+        await ctx.db.patch(args.sandboxRunId, {
+            sandboxId: args.sandboxId,
+            updatedAt: Date.now(),
+        });
+        return null;
+    },
+});
+// getStatus — client-facing read, same org-isolation discipline as every
+// other status query in this engine.
+export const getStatus = query({
+    args: { orgId: v.string(), sandboxRunId: v.id("sandboxRuns") },
+    returns: v.object({
+        status: v.union(v.literal("pending"), v.literal("completed"), v.literal("failed"), v.literal("timedOut")),
+        resultSummary: v.optional(v.string()),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const row = await ctx.db.get(args.sandboxRunId);
+        assertSameOrg(orgId, row, "Sandbox run not found");
+        return { status: row.status, resultSummary: row.resultSummary };
+    },
+});
+// deadLetterMalformed — reached from the consumer app's `convex/http.ts`
+// when a SIGNATURE-VALID request's body is not valid JSON or is missing
+// required fields. The signature already proved the caller holds the
+// shared secret, so this is not a security refusal (that already happened
+// upstream, in the app's own HTTP route, before this ever runs) — it is a
+// shape problem worth a human's attention, recorded rather than dropped.
+// `orgId` is optional: the payload may not have parsed far enough to know
+// which org this delivery even claims to belong to.
+export const deadLetterMalformed = mutation({
+    args: {
+        orgId: v.optional(v.string()),
+        deliveryId: v.string(),
+        reason: v.string(),
+        rawBody: v.string(),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        await ctx.db.insert("sandboxCallbackDeadLetters", {
+            orgId: args.orgId,
+            deliveryId: args.deliveryId,
+            reason: args.reason,
+            rawBody: args.rawBody,
+            createdAt: Date.now(),
+        });
+        return null;
+    },
+});
+// processCallback — THE WAKE, reached ONLY from the consumer app's
+// `convex/http.ts` AFTER signature verification. `deliveryId` dedup is the
+// FIRST read in this transaction, and the "woke" delivery row is inserted
+// in the SAME transaction as the `sendEvent` call — Convex mutations are
+// single transactions, so there is no window in which two concurrent
+// replays of the same `deliveryId` could both observe "not yet delivered"
+// and both wake the workflow. A delivery whose signature verified but
+// whose `sandboxRunId` is unknown, cross-org, or already resolved is
+// DEAD-LETTERED rather than silently dropped or blindly retried.
+export const processCallback = mutation({
+    args: {
+        deliveryId: v.string(),
+        orgId: v.string(),
+        sandboxRunId: v.string(),
+        status: wakeStatus,
+        resultSummary: v.optional(v.string()),
+    },
+    returns: v.object({
+        outcome: v.union(v.literal("woke"), v.literal("duplicate"), v.literal("dead-lettered")),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        if (args.deliveryId.length === 0) {
+            throw new Error("Validation: deliveryId must not be empty");
+        }
+        // Dedup FIRST, inside this same transaction.
+        const existingDelivery = await ctx.db
+            .query("sandboxCallbackDeliveries")
+            .withIndex("by_org_delivery", (q) => q.eq("orgId", orgId).eq("deliveryId", args.deliveryId))
+            .unique();
+        if (existingDelivery) {
+            return { outcome: "duplicate" };
+        }
+        const runId = args.sandboxRunId;
+        const run = await ctx.db.get(runId);
+        if (!run || run.orgId !== orgId) {
+            await ctx.db.insert("sandboxCallbackDeadLetters", {
+                orgId,
+                deliveryId: args.deliveryId,
+                reason: `Unknown or cross-org sandboxRunId "${args.sandboxRunId}"`,
+                rawBody: JSON.stringify(args),
+                createdAt: Date.now(),
+            });
+            return { outcome: "dead-lettered" };
+        }
+        if (run.status !== "pending") {
+            // Already resolved (completed/failed/timedOut) — a signature-valid
+            // callback for a run that is no longer pending is not a legitimate
+            // second wake; record it for human inspection instead of firing
+            // sendEvent again or throwing an unreadable error.
+            await ctx.db.insert("sandboxCallbackDeadLetters", {
+                orgId,
+                deliveryId: args.deliveryId,
+                reason: `sandboxRun ${run._id} already resolved with status "${run.status}"`,
+                rawBody: JSON.stringify(args),
+                createdAt: Date.now(),
+            });
+            return { outcome: "dead-lettered" };
+        }
+        await ctx.db.insert("sandboxCallbackDeliveries", {
+            orgId,
+            sandboxRunId: run._id,
+            deliveryId: args.deliveryId,
+            outcome: "woke",
+            receivedAt: Date.now(),
+        });
+        await ctx.db.patch(run._id, {
+            status: args.status,
+            resultSummary: args.resultSummary,
+            updatedAt: Date.now(),
+        });
+        await workflow.sendEvent(ctx, {
+            workflowId: run.workflowId,
+            name: run.awaitedEventName,
+            validator: v.object({ status: wakeStatus, resultSummary: v.optional(v.string()) }),
+            value: { status: args.status, resultSummary: args.resultSummary },
+        });
+        return { outcome: "woke" };
+    },
+});
+// timeoutInternal — the self-built awaitEvent timeout (workflow#177
+// pattern, same discipline as engine/awaitEventTimeout.ts), scoped to a
+// sandbox run rather than a session. INTERNAL: reached only via
+// `ctx.scheduler.runAfter` from `startRun` above, inside this SAME
+// component — never a cross-component call, so `internalMutation` is
+// correct here (unlike `startRun`/`attachSandboxId`/`processCallback`/
+// `deadLetterMalformed`, which must be reachable from outside). Fires ONLY
+// if the run is still "pending" when the deadline arrives (idempotent
+// against a callback that lands in the same tick); wakes the workflow in a
+// CLEAN FAILURE, not a silent hang.
+export const timeoutInternal = internalMutation({
+    args: { sandboxRunId: v.id("sandboxRuns") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const run = await ctx.db.get(args.sandboxRunId);
+        if (!run || run.status !== "pending") {
+            return null; // already resolved by a real callback, or row gone
+        }
+        await ctx.db.patch(run._id, {
+            status: "timedOut",
+            resultSummary: "Sandbox run timed out before any signed callback arrived",
+            updatedAt: Date.now(),
+        });
+        await workflow.sendEvent(ctx, {
+            workflowId: run.workflowId,
+            name: run.awaitedEventName,
+            validator: v.object({ status: wakeStatus, resultSummary: v.optional(v.string()) }),
+            value: {
+                status: "failed",
+                resultSummary: "Sandbox run timed out before any signed callback arrived",
+            },
+        });
+        return null;
+    },
+});

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

@@ -1,8 +1,12 @@
+import type { Id } from "../_generated/dataModel.js";
 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">>>;
+}, Promise<{
+    sessionId: Id<"sessions">;
+    workflowId: string;
+}>>;
 export declare const sendTurn: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
     sessionId: import("convex/values").GenericId<"sessions">;
@@ -39,7 +43,7 @@ export declare const listEvents: import("convex/server").RegisteredQuery<"public
 }, Promise<{
     _id: import("convex/values").GenericId<"sessionEvents">;
     _creationTime: number;
-    name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.toolCall.denied" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
+    name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.toolCall.denied" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved" | "sandbox.timeout";
     payload: string | undefined;
     createdAt: number;
 }[]>>;

package/dist/component/engine/sessions.js

@@ -1,7 +1,8 @@
 import { v } from "convex/values";
-import { api } from "../_generated/api.js";
+import { api, internal } from "../_generated/api.js";
 import { mutation, query } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
+import { workflow } from "./workflows.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
@@ -23,11 +24,38 @@ async function insertEvent(ctx, args) {
         createdAt: Date.now(),
     });
 }
+const CURRENT_SESSION_WORKFLOW_VERSION = "v1";
 // start — opens a session (session.started boundary), rereading the
-// manifest immediately so a caller can act on it before the first turn.
+// manifest immediately so a caller can act on it before the first turn,
+// then STARTS the durable, versioned session workflow
+// (engine/workflows.ts:sessionWorkflowV1) that pilots this session from
+// here on.
+//
+// RETURN CONTRACT ("intentional divergence from Eve"): `start` returns
+// `{ sessionId, workflowId }` instead of a bare `sessionId`. A bare ID
+// would be the shape for a session with no workflow to reference;
+// once a session IS piloted by a real, durable workflow run, silently
+// dropping that run's id would make it unobservable/uncancellable to
+// every caller except one that re-reads the session row. Returning both
+// fields explicitly, rather than only patching `workflowId` onto the row
+// and making callers re-fetch, keeps `start`'s result self-sufficient for
+// the common "immediately act on the new session" case while the session
+// row remains the durable source of truth for reconnects/replays.
 export const start = mutation({
     args: { orgId: v.string(), agentId: v.id("agents"), createdBy: v.string() },
-    returns: v.id("sessions"),
+    returns: v.object({ sessionId: v.id("sessions"), workflowId: v.string() }),
+    // EXPLICIT return-type annotation ("intentional divergence from Eve" -- Convex pattern for
+    // any handler that references `components`/a WorkflowManager built on
+    // `components.workflow`): `workflow.start` closes over `components`,
+    // which closes back over this component's own generated `api` --
+    // `sessions.start` -> `workflow.start` -> `components` -> `sessions` is
+    // a type-level cycle. Without an explicit handler return type, TS
+    // widens the inferred return to `any` while resolving that cycle, and
+    // `.d.ts` EMISSION (declaration:true, tsconfig.build.json) fails --
+    // TS2502/TS2615/TS7022 -- even though `tsc --noEmit` at the repo root
+    // stays green (noEmit skips the exact codepath that breaks). Measured
+    // on PR #13 (build gate review): `npm run build` is the build that SHIPS; a
+    // green `tsc --noEmit` is not sufficient proof by itself.
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
         if (args.createdBy.trim().length === 0) {
@@ -49,7 +77,12 @@ export const start = mutation({
             orgId,
             sessionId,
         });
-        return sessionId;
+        const workflowId = await workflow.start(ctx, internal.engine.workflows.sessionWorkflowV1, { sessionId });
+        await ctx.db.patch(sessionId, {
+            workflowId,
+            workflowVersion: CURRENT_SESSION_WORKFLOW_VERSION,
+        });
+        return { sessionId, workflowId };
     },
 });
 // sendTurn — turn.started boundary. Rereads the manifest (eve parity: dynamic
@@ -154,8 +187,8 @@ export const requestToolCall = mutation({
         // approval === "once": gate unless this tool's approval was already
         // resolved with `decision: "approved"` in this session. A prior
         // `decision: "denied"` resolution must NOT be treated as
-        // authorization (that was the pre-alpha.5 bug -- "outil sauté, tour
-        // complété quand même") -- it is reported back as a terminal refusal
+        // authorization (the tool would be skipped while the turn still
+        // completed) -- it is reported back as a terminal refusal
         // instead, and the caller re-requests (a fresh human decision) rather
         // than silently proceeding.
         const events = await ctx.db
@@ -237,7 +270,10 @@ export const listEvents = query({
     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.toolCall.denied"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved")),
+        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.toolCall.denied"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved"), 
+        // Blank event auto-inserted by
+        // `engine/awaitEventTimeout.fire` (workflow#177).
+        v.literal("sandbox.timeout")),
         payload: v.optional(v.string()),
         createdAt: v.number(),
     })),

package/dist/component/engine/toolApprovals.js

@@ -10,7 +10,7 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 //   1. `decision` -- the RESPONSE to THIS ONE pending approval request,
 //      for THIS turn only. Vocabulary aligned with Eve's `ApprovalStatus`
 //      (packages/eve/src/public/definitions/approval.ts: "approved" |
-//      "denied" | ...) -- eve parity, cited verbatim, not "notre ligne".
+//      "denied" | ...) -- eve parity, cited verbatim, not "intentional divergence from Eve".
 //      `"denied"` means: this turn's tool call is refused, full stop. It
 //      does NOT change the agent's standing policy for the tool, and it
 //      must NOT be interpreted as "tool skipped, turn completed anyway" --

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

@@ -0,0 +1,69 @@
+export declare const defaultToggles: {
+    readonly memoryEnabled: true;
+    readonly tasksEnabled: true;
+    readonly messagesEnabled: true;
+    readonly notesEnabled: true;
+};
+export declare const get: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"vpConnections">;
+    _creationTime: number;
+    orgId: string;
+    createdAt: number;
+    updatedAt: number;
+    agentId: import("convex/values").GenericId<"agents">;
+    memoryEnabled: boolean;
+    tasksEnabled: boolean;
+    messagesEnabled: boolean;
+    notesEnabled: boolean;
+} | null>>;
+export declare const getToggles: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<{
+    readonly memoryEnabled: true;
+    readonly tasksEnabled: true;
+    readonly messagesEnabled: true;
+    readonly notesEnabled: true;
+} | {
+    memoryEnabled: boolean;
+    tasksEnabled: boolean;
+    messagesEnabled: boolean;
+    notesEnabled: boolean;
+}>>;
+export declare const setToggles: import("convex/server").RegisteredMutation<"public", {
+    memoryEnabled?: boolean | undefined;
+    tasksEnabled?: boolean | undefined;
+    messagesEnabled?: boolean | undefined;
+    notesEnabled?: boolean | undefined;
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<import("convex/values").GenericId<"vpConnections">>>;
+export declare const invokeVpTool: import("convex/server").RegisteredAction<"public", {
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+    tool: "memory" | "tasks" | "messages" | "notes";
+    argsJson: string;
+    vpFunctionHandle: string;
+}, Promise<null>>;
+export declare const getTogglesInternal: import("convex/server").RegisteredQuery<"internal", {
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<{
+    readonly memoryEnabled: true;
+    readonly tasksEnabled: true;
+    readonly messagesEnabled: true;
+    readonly notesEnabled: true;
+} | {
+    memoryEnabled: boolean;
+    tasksEnabled: boolean;
+    messagesEnabled: boolean;
+    notesEnabled: boolean;
+} | null>>;
+export declare const recordInvocationInternal: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+    tool: "memory" | "tasks" | "messages" | "notes";
+}, Promise<null>>;

package/dist/component/engine/vpConnection.js

@@ -0,0 +1,218 @@
+import { v } from "convex/values";
+import { action, internalMutation, internalQuery, mutation, query, } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
+import { internal } from "../_generated/api.js";
+// engine/vpConnection — teamwork. The four VantagePeers tools
+// (memory, tasks, messages, notes) are wired as a CONNECTION of the agent
+// aggregate -- intentional divergence from Eve, same slot family as `connections` (MCP/OpenAPI).
+// Four toggles, ON by default.
+//
+// DIRECT ACCESS, NO NETWORK IN THE HOT PATH: `invokeVpTool` dispatches via a
+// caller-supplied Convex function handle (`createFunctionHandle`), the same
+// discipline `engine/wakeup.ts` and `engine/durableJob.ts` already use for
+// `workFunctionHandle` / `stepFunctionHandle` -- an in-process function
+// reference resolved by `ctx.runMutation`, never an HTTP request: this file
+// contains zero occurrences of the literal fetch call.
+//
+// orgId discipline (component/lib/auth.ts): every PUBLIC function takes
+// `orgId` as an explicit ARGUMENT (auth does not propagate across a
+// component boundary). `orgId` is passed EXPLICITLY to the target function
+// handle (never trusting the target's own `ctx.auth`) -- this is the
+// isolation guarantee the org-scoped write depends on: the target function
+// is expected to write scoped to the `orgId` it was HANDED, not to derive
+// one itself.
+const vpTool = v.union(v.literal("memory"), v.literal("tasks"), v.literal("messages"), v.literal("notes"));
+// defaultToggles — four switches, all ticked by default. A
+// missing `vpConnections` row means "use these defaults", so every agent
+// starts with all four VP tools available with zero extra setup.
+export const defaultToggles = {
+    memoryEnabled: true,
+    tasksEnabled: true,
+    messagesEnabled: true,
+    notesEnabled: true,
+};
+const vpConnectionDoc = v.object({
+    _id: v.id("vpConnections"),
+    _creationTime: v.number(),
+    orgId: v.string(),
+    agentId: v.id("agents"),
+    memoryEnabled: v.boolean(),
+    tasksEnabled: v.boolean(),
+    messagesEnabled: v.boolean(),
+    notesEnabled: v.boolean(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+// get — the raw connection row, if a human ever touched the toggles.
+export const get = query({
+    args: { orgId: v.string(), agentId: v.id("agents") },
+    returns: v.union(vpConnectionDoc, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const agent = await ctx.db.get(args.agentId);
+        assertSameOrg(orgId, agent, "Agent not found");
+        return await ctx.db
+            .query("vpConnections")
+            .withIndex("by_org_agent", (q) => q.eq("orgId", orgId).eq("agentId", args.agentId))
+            .unique();
+    },
+});
+// getToggles — resolves the effective toggle state (row if present, else
+// the checked-by-default set) for a given agent.
+export const getToggles = query({
+    args: { orgId: v.string(), agentId: v.id("agents") },
+    returns: v.object({
+        memoryEnabled: v.boolean(),
+        tasksEnabled: v.boolean(),
+        messagesEnabled: v.boolean(),
+        notesEnabled: v.boolean(),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const agent = await ctx.db.get(args.agentId);
+        assertSameOrg(orgId, agent, "Agent not found");
+        const row = await ctx.db
+            .query("vpConnections")
+            .withIndex("by_org_agent", (q) => q.eq("orgId", orgId).eq("agentId", args.agentId))
+            .unique();
+        return row
+            ? {
+                memoryEnabled: row.memoryEnabled,
+                tasksEnabled: row.tasksEnabled,
+                messagesEnabled: row.messagesEnabled,
+                notesEnabled: row.notesEnabled,
+            }
+            : defaultToggles;
+    },
+});
+// setToggles — upserts the four switches (an explicit human choice to turn
+// one off; still ON by default until touched).
+export const setToggles = mutation({
+    args: {
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        memoryEnabled: v.optional(v.boolean()),
+        tasksEnabled: v.optional(v.boolean()),
+        messagesEnabled: v.optional(v.boolean()),
+        notesEnabled: v.optional(v.boolean()),
+    },
+    returns: v.id("vpConnections"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const agent = await ctx.db.get(args.agentId);
+        assertSameOrg(orgId, agent, "Agent not found");
+        const existing = await ctx.db
+            .query("vpConnections")
+            .withIndex("by_org_agent", (q) => q.eq("orgId", orgId).eq("agentId", args.agentId))
+            .unique();
+        const now = Date.now();
+        const merged = {
+            memoryEnabled: args.memoryEnabled ?? existing?.memoryEnabled ?? defaultToggles.memoryEnabled,
+            tasksEnabled: args.tasksEnabled ?? existing?.tasksEnabled ?? defaultToggles.tasksEnabled,
+            messagesEnabled: args.messagesEnabled ?? existing?.messagesEnabled ?? defaultToggles.messagesEnabled,
+            notesEnabled: args.notesEnabled ?? existing?.notesEnabled ?? defaultToggles.notesEnabled,
+        };
+        if (existing) {
+            await ctx.db.patch(existing._id, { ...merged, updatedAt: now });
+            return existing._id;
+        }
+        return await ctx.db.insert("vpConnections", {
+            orgId,
+            agentId: args.agentId,
+            ...merged,
+            createdAt: now,
+            updatedAt: now,
+        });
+    },
+});
+function toggleFor(toggles, tool) {
+    return tool === "memory"
+        ? toggles.memoryEnabled
+        : tool === "tasks"
+            ? toggles.tasksEnabled
+            : tool === "messages"
+                ? toggles.messagesEnabled
+                : toggles.notesEnabled;
+}
+// invokeVpTool — the direct-access dispatch. `vpFunctionHandle` is an
+// opaque handle string obtained via `createFunctionHandle` against a
+// mutation the VantagePeers tenant exposes (same-app or cross-app handle,
+// per Convex's own `createFunctionHandle` contract -- never a URL, never an
+// HTTP fetch call). The engine passes `orgId` EXPLICITLY as an argument
+// (never trusting the target's own `ctx.auth`, since this may cross an
+// app/component boundary) -- this is the isolation guarantee the org-scoped
+// write depends on: the target function is expected to write scoped to the
+// `orgId` it was HANDED, not to derive one itself.
+export const invokeVpTool = action({
+    args: {
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        tool: vpTool,
+        vpFunctionHandle: v.string(),
+        argsJson: v.string(),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const toggles = await ctx.runQuery(internal.engine.vpConnection.getTogglesInternal, {
+            orgId,
+            agentId: args.agentId,
+        });
+        if (!toggles) {
+            throw new Error("Agent not found");
+        }
+        if (!toggleFor(toggles, args.tool)) {
+            throw new Error(`VantagePeers tool "${args.tool}" is disabled for this agent`);
+        }
+        // In-process dispatch by function handle -- NOT an HTTP fetch call, NOT
+        // an HTTP hop. `orgId` is threaded explicitly so the write lands in the
+        // CALLING agent's org tenant regardless of which org's identity (if
+        // any) the target function's own `ctx.auth` would otherwise resolve.
+        await ctx.runMutation(args.vpFunctionHandle, { orgId, argsJson: args.argsJson });
+        await ctx.runMutation(internal.engine.vpConnection.recordInvocationInternal, {
+            orgId,
+            agentId: args.agentId,
+            tool: args.tool,
+        });
+        return null;
+    },
+});
+export const getTogglesInternal = internalQuery({
+    args: { orgId: v.string(), agentId: v.id("agents") },
+    returns: v.union(v.object({
+        memoryEnabled: v.boolean(),
+        tasksEnabled: v.boolean(),
+        messagesEnabled: v.boolean(),
+        notesEnabled: v.boolean(),
+    }), v.null()),
+    handler: async (ctx, args) => {
+        const agent = await ctx.db.get(args.agentId);
+        if (!agent || agent.orgId !== args.orgId)
+            return null;
+        const row = await ctx.db
+            .query("vpConnections")
+            .withIndex("by_org_agent", (q) => q.eq("orgId", args.orgId).eq("agentId", args.agentId))
+            .unique();
+        return row
+            ? {
+                memoryEnabled: row.memoryEnabled,
+                tasksEnabled: row.tasksEnabled,
+                messagesEnabled: row.messagesEnabled,
+                notesEnabled: row.notesEnabled,
+            }
+            : defaultToggles;
+    },
+});
+export const recordInvocationInternal = internalMutation({
+    args: { orgId: v.string(), agentId: v.id("agents"), tool: vpTool },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        await ctx.db.insert("vpToolInvocations", {
+            orgId: args.orgId,
+            agentId: args.agentId,
+            tool: args.tool,
+            createdAt: Date.now(),
+        });
+        return null;
+    },
+});