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

package/dist/component/engine/sandboxCallback.js

@@ -0,0 +1,262 @@
+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 — C5: THE SIGNED CALLBACK GATE'S DB-SIDE LOGIC,
+// PORTED from convex/engine/sandboxCallback.ts (repo-root prototype, I5,
+// SYNTHESE.md §4.c-d, i0-research §8/§5) into the component boundary.
+//
+// NOTRE LIGNE (C5 recherche-d'abord, see component/schema.ts's C5 header
+// comment for the measured verdict + citations):
+//   - 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
+//     (convex/engine/sandboxBridgeActions.ts) 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, see component/engine/mandates.ts's
+//     `spendInternal` for the same convention already established in C3).
+//
+// 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">;
@@ -21,6 +25,7 @@ export declare const requestToolCall: import("convex/server").RegisteredMutation
 }, Promise<{
     authorized: boolean;
     approvalPending: boolean;
+    denied: boolean;
 }>>;
 export declare const completeToolCall: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
@@ -38,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.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,39 @@ 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 (C1.5 -- retires the T2-QUINQUIES "sessions are just an event
+// table" divergence).
+//
+// RETURN CONTRACT ("notre ligne", C1.5): `start` now returns
+// `{ sessionId, workflowId }` instead of a bare `sessionId`. A bare ID
+// return was the pre-C1.5 shape when no workflow existed 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 ("notre ligne" -- 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 (Eta gate): `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 +78,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
@@ -112,7 +146,15 @@ export const requestToolCall = mutation({
         toolName: v.string(),
         argsJson: v.string(),
     },
-    returns: v.object({ authorized: v.boolean(), approvalPending: v.boolean() }),
+    returns: v.object({
+        authorized: v.boolean(),
+        approvalPending: v.boolean(),
+        // Explicit terminal refusal for THIS turn (VP
+        // k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2). Distinct from
+        // `approvalPending: false, authorized: true` (approved/never-gated)
+        // -- a caller must check this before treating the call as skippable.
+        denied: v.boolean(),
+    }),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
         const session = await ctx.db.get(args.sessionId);
@@ -132,7 +174,7 @@ export const requestToolCall = mutation({
             .unique();
         const approval = approvalRow?.approval ?? "never";
         if (approval === "never") {
-            return { authorized: true, approvalPending: false };
+            return { authorized: true, approvalPending: false, denied: false };
         }
         if (approval === "always") {
             await insertEvent(ctx, {
@@ -141,20 +183,35 @@ export const requestToolCall = mutation({
                 name: "tool.approval.requested",
                 payload: JSON.stringify({ toolName: args.toolName }),
             });
-            return { authorized: false, approvalPending: true };
+            return { authorized: false, approvalPending: true, denied: false };
         }
-        // approval === "once": gate unless this tool was already resolved once
-        // in this session.
+        // 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
+        // instead, and the caller re-requests (a fresh human decision) rather
+        // than silently proceeding.
         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" &&
+        const resolutionsForTool = events
+            .filter((e) => e.name === "tool.approval.resolved" &&
             e.payload !== undefined &&
             JSON.parse(e.payload).toolName ===
-                args.toolName);
-        if (alreadyResolvedThisSession) {
-            return { authorized: true, approvalPending: false };
+                args.toolName)
+            .sort((a, b) => a.createdAt - b.createdAt);
+        const latestResolution = resolutionsForTool[resolutionsForTool.length - 1];
+        const latestDecision = latestResolution?.payload
+            ? JSON.parse(latestResolution.payload)
+                .decision
+            : undefined;
+        if (latestDecision === "approved") {
+            return { authorized: true, approvalPending: false, denied: false };
+        }
+        if (latestDecision === "denied") {
+            return { authorized: false, approvalPending: false, denied: true };
         }
         await insertEvent(ctx, {
             orgId,
@@ -162,7 +219,7 @@ export const requestToolCall = mutation({
             name: "tool.approval.requested",
             payload: JSON.stringify({ toolName: args.toolName }),
         });
-        return { authorized: false, approvalPending: true };
+        return { authorized: false, approvalPending: true, denied: false };
     },
 });
 // completeToolCall — the caller invokes this after actually running the
@@ -214,7 +271,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.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"), 
+        // C2 — 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.d.ts

@@ -1,6 +1,7 @@
 export declare const respond: import("convex/server").RegisteredMutation<"public", {
+    updatePolicy?: "always" | "once" | "never" | undefined;
     orgId: string;
     toolName: string;
-    approval: "always" | "once" | "never";
     sessionId: import("convex/values").GenericId<"sessions">;
+    decision: "approved" | "denied";
 }, Promise<null>>;

package/dist/component/engine/toolApprovals.js

@@ -2,51 +2,89 @@ import { v } from "convex/values";
 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
-// 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.
+// (`tool.approval.requested`, raised by `sessions.requestToolCall`).
+//
+// TWO DISTINCT AXES (VP k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2 --
+// these were conflated pre-alpha.5, which is the defect this fixes):
+//
+//   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"` 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" --
+//      it appends a `turn.toolCall.denied` sessionEvent instead of letting
+//      the caller silently proceed to `completeToolCall`.
+//
+//   2. `updatePolicy` -- optional, persists a NEW standing policy
+//      (always | once | never, eve parity: eve/tools/approval helpers) for
+//      this (agent, tool) pair going forward, upserted on
+//      `by_org_agent_tool`. Independent of `decision`: a human can deny
+//      this turn's call AND leave the policy untouched (ask again next
+//      time), or approve this turn AND simultaneously flip the policy to
+//      "always"/"never" so future calls don't pause.
 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")),
+        decision: v.union(v.literal("approved"), v.literal("denied")),
+        updatePolicy: v.optional(v.union(v.literal("always"), v.literal("once"), v.literal("never"))),
     },
     returns: v.null(),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
         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,
-            });
+        if (args.updatePolicy !== undefined) {
+            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();
+            if (existing) {
+                await ctx.db.patch(existing._id, {
+                    approval: args.updatePolicy,
+                    updatedAt: now,
+                });
+            }
+            else {
+                await ctx.db.insert("toolApprovals", {
+                    orgId,
+                    agentId: session.agentId,
+                    toolName: args.toolName,
+                    approval: args.updatePolicy,
+                    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 }),
+            payload: JSON.stringify({
+                toolName: args.toolName,
+                decision: args.decision,
+                updatedPolicy: args.updatePolicy ?? null,
+            }),
             createdAt: now,
         });
+        if (args.decision === "denied") {
+            // Explicit refusal state for THIS turn's tool call -- never a
+            // silent "turn.toolCall.completed". See module doc above.
+            await ctx.db.insert("sessionEvents", {
+                orgId,
+                sessionId: args.sessionId,
+                name: "turn.toolCall.denied",
+                payload: JSON.stringify({ toolName: args.toolName }),
+                createdAt: now,
+            });
+        }
         return null;
     },
 });

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>>;