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

package/README.md

@@ -214,10 +214,31 @@ Two gates now exist, and they check different things:
    hand-edit of existing generated content.**
 2. **Content, requires a live deployment** --
    `scripts/check-generated-content.mjs` (`npm run
-   check:generated:content`). Actually runs `npx convex codegen` against
-   the dev deployment and diffs `convex/_generated/` byte-for-byte
-   (`git diff --exit-code`). Catches everything, including a single hand-
-   edited character.
+   check:generated:content`). Runs `npx convex codegen` against the dev
+   deployment for BOTH `convex/_generated/` (the host repo's own dev
+   deployment bindings) AND, since 0.1.0-alpha.5, `component/_generated/`
+   via `npx convex codegen --component-dir component` -- the checked-in
+   file `tsc -p tsconfig.build.json` copies verbatim into the PUBLISHED
+   `dist/component/_generated/component.d.ts`, i.e. the exact type a
+   consuming app checks `components.agentEngine.*` calls against. Diffs
+   each byte-for-byte (`git diff --exit-code`). Catches everything,
+   including a single hand-edited character.
+
+   **`component/_generated/` was NOT covered before 0.1.0-alpha.5** — that
+   gap is why `0.1.0-alpha.4` shipped a `component.d.ts` stale against the
+   real component schema (missing `orgId`/`createdBy` on
+   sessions/agents/durableJob/toolApprovals args), which broke
+   `tsc --noEmit` for any consumer calling `sessions.start`/`durableJob.start`
+   with `orgId` (Hestia, VP k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 1).
+   The visibility (`"internal"`) on every entry is, by measured comparison
+   against `@convex-dev/rate-limiter`'s own published `component.d.ts`,
+   CORRECT and unrelated to that defect — every official Convex component
+   types its cross-component `ComponentApi` as `"internal"` regardless of
+   whether the underlying function is declared `mutation`/`query` or
+   `internalMutation`/`internalQuery`; `ctx.runMutation`'s own signature
+   (`convex/server`) accepts `FunctionReference<"mutation", "public" |
+   "internal">` either way. The root cause was staleness of the args
+   shape, not visibility.
 
    **Three-state exit contract** (never two -- a two-state gate cannot
    distinguish "I measured, it's clean" from "I could not measure at
@@ -389,14 +410,43 @@ components.agentEngine.engine.resolvers.resolveManifest({ orgId, sessionId }) ->
 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.requestToolCall({ orgId, sessionId, toolName, argsJson }) -> { authorized, approvalPending, denied }
 components.agentEngine.engine.sessions.completeToolCall({ orgId, sessionId, toolName, resultJson }) -> null
 components.agentEngine.engine.sessions.completeTurn({ orgId, sessionId }) -> null
 components.agentEngine.engine.sessions.listEvents({ orgId, sessionId }) -> sessionEvent[]
 
-components.agentEngine.engine.toolApprovals.respond({ orgId, sessionId, toolName, approval: "always"|"once"|"never" }) -> null
+components.agentEngine.engine.toolApprovals.respond({ orgId, sessionId, toolName, decision: "approved"|"denied", updatePolicy?: "always"|"once"|"never" }) -> null
 ```
 
+### `toolApprovals.respond` — `decision` vs `updatePolicy` (0.1.0-alpha.5)
+
+Two DISTINCT axes were conflated pre-alpha.5 (VP
+k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2) — a single `approval:
+"always"|"once"|"never"` argument was overloaded to mean both "the standing
+policy for this tool" AND "the answer to this one pending request", and
+there was no literal for "refuse this turn only". Fixed by splitting them:
+
+- **`decision`** (required) — the response to THIS ONE pending
+  `tool.approval.requested` event, for THIS turn only. `"approved"` |
+  `"denied"`. **Eve parity, direct** — vocabulary matches Eve's
+  `ApprovalStatus` (`packages/eve/src/public/definitions/approval.ts`:
+  `"approved" | "denied" | "not-applicable" | "user-approval" | ...`); we
+  did not invent a `deny` literal, we aligned with the one Eve already has.
+  `"denied"` is a terminal refusal for the turn: `sessions.requestToolCall`
+  reports back `{ authorized: false, approvalPending: false, denied: true
+  }` (never re-authorized on retry within the session), and a dedicated
+  `turn.toolCall.denied` sessionEvent is appended — there is NO
+  `turn.toolCall.completed` for a denied call, i.e. the tool was never run
+  and the turn is NOT silently treated as done.
+- **`updatePolicy`** (optional) — persists a NEW standing gate
+  (`"always"|"once"|"never"`, eve parity: `eve/tools/approval` helpers) for
+  this `(agentId, toolName)` pair going forward, independent of `decision`.
+  A human can deny this turn's call and leave the policy alone (ask again
+  next time), or approve this turn and simultaneously flip the policy to
+  `"always"`/`"never"` so future calls stop pausing. `"never"` still means
+  Eve's "never require approval" (auto-authorize) — that policy literal is
+  unchanged and is NOT the same thing as a `"denied"` decision.
+
 `createdBy` (on `agents.create` / `sessions.start`) is, for the same
 platform reason as `orgId`, no longer read from `ctx.auth.getUserIdentity()`
 — the consumer passes the acting user's own identifier.

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

@@ -22,12 +22,15 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
     engine: {
         agents: {
             create: FunctionReference<"mutation", "internal", {
+                createdBy: string;
                 instructions: string;
                 model: string;
                 name: string;
+                orgId: string;
             }, string, Name>;
             get: FunctionReference<"query", "internal", {
                 agentId: string;
+                orgId: string;
             }, {
                 _creationTime: number;
                 _id: string;
@@ -44,9 +47,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         durableJob: {
             cancel: FunctionReference<"mutation", "internal", {
                 jobId: string;
+                orgId: string;
             }, null, Name>;
             getStatus: FunctionReference<"query", "internal", {
                 jobId: string;
+                orgId: string;
             }, {
                 abandonedAtStep?: number;
                 cursor: number;
@@ -57,12 +62,14 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             start: FunctionReference<"mutation", "internal", {
                 kind: string;
                 maxAttemptsPerStep: number;
+                orgId: string;
                 stepFunctionHandle: string;
                 totalSteps: number;
             }, string, Name>;
         };
         resolvers: {
             resolveManifest: FunctionReference<"query", "internal", {
+                orgId: string;
                 sessionId: string;
             }, {
                 agentId: string;
@@ -78,46 +85,57 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         sessions: {
             appendReasoning: FunctionReference<"mutation", "internal", {
                 chunk: string;
+                orgId: string;
                 sessionId: string;
             }, null, Name>;
             completeToolCall: FunctionReference<"mutation", "internal", {
+                orgId: string;
                 resultJson: string;
                 sessionId: string;
                 toolName: string;
             }, null, Name>;
             completeTurn: FunctionReference<"mutation", "internal", {
+                orgId: string;
                 sessionId: string;
             }, null, Name>;
             listEvents: FunctionReference<"query", "internal", {
+                orgId: string;
                 sessionId: string;
             }, Array<{
                 _creationTime: number;
                 _id: string;
                 createdAt: number;
-                name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
+                name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.toolCall.denied" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
                 payload?: string;
             }>, Name>;
             requestToolCall: FunctionReference<"mutation", "internal", {
                 argsJson: string;
+                orgId: string;
                 sessionId: string;
                 toolName: string;
             }, {
                 approvalPending: boolean;
                 authorized: boolean;
+                denied: boolean;
             }, Name>;
             sendTurn: FunctionReference<"mutation", "internal", {
                 input: string;
+                orgId: string;
                 sessionId: string;
             }, null, Name>;
             start: FunctionReference<"mutation", "internal", {
                 agentId: string;
+                createdBy: string;
+                orgId: string;
             }, string, Name>;
         };
         toolApprovals: {
             respond: FunctionReference<"mutation", "internal", {
-                approval: "always" | "once" | "never";
+                decision: "approved" | "denied";
+                orgId: string;
                 sessionId: string;
                 toolName: string;
+                updatePolicy?: "always" | "once" | "never";
             }, null, Name>;
         };
     };

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

@@ -21,6 +21,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 +39,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";
     payload: string | undefined;
     createdAt: number;
 }[]>>;

package/dist/component/engine/sessions.js

@@ -112,7 +112,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 +140,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 +149,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 +185,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 +237,7 @@ 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")),
         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/schema.d.ts

@@ -106,14 +106,14 @@ declare const _default: import("convex/server").SchemaDefinition<{
     }, {}, {}>;
     sessionEvents: import("convex/server").TableDefinition<import("convex/values").VObject<{
         payload?: string | undefined;
-        name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
+        name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.toolCall.denied" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
         orgId: string;
         createdAt: number;
         sessionId: import("convex/values").GenericId<"sessions">;
     }, {
         orgId: import("convex/values").VString<string, "required">;
         sessionId: import("convex/values").VId<import("convex/values").GenericId<"sessions">, "required">;
-        name: import("convex/values").VUnion<"session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved", [import("convex/values").VLiteral<"session.started", "required">, import("convex/values").VLiteral<"turn.started", "required">, import("convex/values").VLiteral<"turn.reasoning", "required">, import("convex/values").VLiteral<"turn.toolCall.requested", "required">, import("convex/values").VLiteral<"turn.toolCall.completed", "required">, import("convex/values").VLiteral<"turn.completed", "required">, import("convex/values").VLiteral<"tool.approval.requested", "required">, import("convex/values").VLiteral<"tool.approval.resolved", "required">], "required", never>;
+        name: import("convex/values").VUnion<"session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.toolCall.denied" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved", [import("convex/values").VLiteral<"session.started", "required">, import("convex/values").VLiteral<"turn.started", "required">, import("convex/values").VLiteral<"turn.reasoning", "required">, import("convex/values").VLiteral<"turn.toolCall.requested", "required">, import("convex/values").VLiteral<"turn.toolCall.completed", "required">, import("convex/values").VLiteral<"turn.toolCall.denied", "required">, import("convex/values").VLiteral<"turn.completed", "required">, import("convex/values").VLiteral<"tool.approval.requested", "required">, import("convex/values").VLiteral<"tool.approval.resolved", "required">], "required", never>;
         payload: import("convex/values").VString<string | undefined, "optional">;
         createdAt: import("convex/values").VFloat64<number, "required">;
     }, "required", "name" | "orgId" | "createdAt" | "sessionId" | "payload">, {

package/dist/component/schema.js

@@ -121,7 +121,14 @@ export default defineSchema({
     sessionEvents: defineTable({
         orgId: v.string(),
         sessionId: v.id("sessions"),
-        name: v.union(v.literal("session.started"), v.literal("turn.started"), v.literal("turn.reasoning"), v.literal("turn.toolCall.requested"), v.literal("turn.toolCall.completed"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved")),
+        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"), 
+        // "notre ligne" (VP k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2):
+        // explicit terminal state for a one-turn approval REFUSAL, distinct
+        // from "turn.toolCall.completed" (tool actually ran). Without this,
+        // a denied tool call had no event of its own -- a consumer had no
+        // way to tell "refused this turn" from "skipped, turn completed
+        // anyway", which is the wrong default Hestia had to code around.
+        v.literal("turn.toolCall.denied"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved")),
         payload: v.optional(v.string()), // JSON-serialized, free contract per event name
         createdAt: v.number(),
     })

package/package.json

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