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

package/dist/component/engine/sessions.js

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

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

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

package/dist/component/engine/toolApprovals.js

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

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

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

package/dist/component/lib/auth.js

@@ -0,0 +1,24 @@
+// 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");
+    }
+    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.
+export function assertSameOrg(callerOrgId, doc, notFoundMessage) {
+    if (!doc || doc.orgId !== callerOrgId) {
+        // Same error for "not found" and "cross-org" -- do not leak existence.
+        throw new Error(notFoundMessage);
+    }
+}

package/dist/component/schema.d.ts

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

package/dist/component/schema.js

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

package/dist/component/testFixtures/callerSteps.d.ts

@@ -0,0 +1,20 @@
+export declare const getAttemptCount: import("convex/server").RegisteredQuery<"internal", {
+    jobId: import("convex/values").GenericId<"durableJobs">;
+    stepIndex: number;
+}, Promise<number>>;
+export declare const resetAttemptCounts: import("convex/server").RegisteredMutation<"internal", {}, Promise<null>>;
+export declare const alwaysSucceeds: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    jobId: import("convex/values").GenericId<"durableJobs">;
+    stepIndex: number;
+}, Promise<null>>;
+export declare const alwaysFails: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    jobId: import("convex/values").GenericId<"durableJobs">;
+    stepIndex: number;
+}, Promise<never>>;
+export declare const failsFirstAttemptThenSucceeds: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    jobId: import("convex/values").GenericId<"durableJobs">;
+    stepIndex: number;
+}, Promise<null>>;