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

package/dist/component/_generated/server.js

@@ -0,0 +1,77 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import { actionGeneric, httpActionGeneric, queryGeneric, mutationGeneric, internalActionGeneric, internalMutationGeneric, internalQueryGeneric, } from "convex/server";
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query = queryGeneric;
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery = internalQueryGeneric;
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation = mutationGeneric;
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation = internalMutationGeneric;
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action = actionGeneric;
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction = internalActionGeneric;
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction = httpActionGeneric;

package/dist/component/convex.config.js

@@ -12,28 +12,26 @@ import agent from "@convex-dev/agent/convex.config";
 //   import agentEngine from "@vantageos/agent-engine/convex.config";
 //   app.use(agentEngine);
 //
-// NOTRE LIGNE / KNOWN GAP (say it here, at the point of read, not only in
-// a message — T2-TER instruction): this file declares agent-engine's
-// COMPONENT IDENTITY and its sub-component composition
-// (workflow + 2 named workpools + agent), which is exactly what makes the
-// `@vantageos/agent-engine/convex.config` import RESOLVE for a consumer
-// and what makes `app.use(agentEngine)` build without throwing.
+// This file declares agent-engine's COMPONENT IDENTITY and its
+// sub-component composition (workflow + 2 named workpools + agent), which
+// is what makes the `@vantageos/agent-engine/convex.config` import
+// RESOLVE for a consumer and what makes `app.use(agentEngine)` build
+// without throwing.
 //
-// It does NOT yet re-host this repo's schema (convex/schema.ts) and
-// functions (convex/agents.ts, convex/skills.ts, convex/engine/**) inside
-// this component boundary, so a consumer cannot yet call
-// `components.agentEngine.agents.create` / `components.agentEngine.engine
-// .durableJob.start` etc. through the published component -- those
-// functions still only exist in this repo's OWN dev/test deployment
-// (convex/convex.config.ts, defineApp, used by `npx convex dev` and
-// convex-test). That migration (moving schema.ts + agents.ts + skills.ts +
-// engine/** under convex/component/, regenerating this component's OWN
-// convex/component/_generated/ against a real component-hosting
-// deployment, and re-verifying every existing test) is real, non-trivial
-// work that was NOT attempted in this packaging pass -- doing it
-// unverified would have violated Day 128 (never weaken/bypass a test to
-// make it pass) by shipping schema/function code with no working
-// convex-test harness behind it. It is the next, separately-scoped task.
+// T2-QUATER (this pass): `convex/component/engine/durableJob.ts` +
+// `convex/component/schema.ts` (its `durableJobs` table) +
+// `convex/component/lib/auth.ts` (orgId isolation) are now CO-LOCATED in
+// this same directory tree, alongside this file — this is what a
+// consumer's `npx convex dev`/`deploy` actually bundles and deploys under
+// the component boundary, and what makes
+// `components.agentEngine.engine.durableJob.start(...)` resolve to a real
+// function instead of `undefined`. See README.md "What's callable" for
+// the exact, current boundary: durableJob is IN; the rest of the agent
+// aggregate (agents, skills, subagents, connections, habits,
+// sandboxConfig, toolApprovals, modelKeys, sessions, sessionEvents,
+// awaitEventTimeouts, wakeableWork) is deliberately NOT yet re-hosted
+// here — porting those without a working component-level test harness
+// behind each of them would violate Day 128 (never ship unverified).
 const component = defineComponent("agentEngine");
 component.use(workflow);
 component.use(workpool, { name: "agentTurnPool" });

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

@@ -0,0 +1,19 @@
+export declare const create: import("convex/server").RegisteredMutation<"public", {
+    name: string;
+    instructions: string;
+    model: string;
+}, Promise<import("convex/values").GenericId<"agents">>>;
+export declare const get: import("convex/server").RegisteredQuery<"public", {
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"agents">;
+    _creationTime: number;
+    name: string;
+    orgId: string;
+    status: "draft" | "live" | "archived";
+    createdAt: number;
+    updatedAt: number;
+    instructions: string;
+    model: string;
+    createdBy: string;
+} | null>>;

package/dist/component/engine/agents.js

@@ -0,0 +1,67 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+import { requireOrgId } from "../lib/auth";
+// engine/agents — MINIMAL root-sheet bootstrap for the sessions surface
+// (T2-QUINQUIES). `sessions.start` needs an `agentId` it can read INSIDE
+// the component boundary (component isolation: it cannot reach into a
+// consumer app's own `agents` table). This is deliberately narrow: only
+// `create`/`get`, no `update`/`list`/skills/connections — the full agent
+// aggregate CRUD stays out of this component boundary for this pass (see
+// component/schema.ts SCOPE note).
+const agentDoc = v.object({
+    _id: v.id("agents"),
+    _creationTime: v.number(),
+    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(),
+});
+export const create = mutation({
+    args: {
+        name: v.string(),
+        instructions: v.string(),
+        model: v.string(),
+    },
+    returns: v.id("agents"),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const identity = await ctx.auth.getUserIdentity();
+        if (!identity)
+            throw new Error("Unauthenticated");
+        if (args.name.trim().length === 0) {
+            throw new Error("Validation: name must not be empty");
+        }
+        if (args.instructions.trim().length === 0) {
+            throw new Error("Validation: instructions must not be empty");
+        }
+        if (args.model.trim().length === 0) {
+            throw new Error("Validation: model must not be empty");
+        }
+        const now = Date.now();
+        return await ctx.db.insert("agents", {
+            orgId,
+            name: args.name,
+            instructions: args.instructions,
+            model: args.model,
+            status: "live",
+            createdBy: identity.subject,
+            createdAt: now,
+            updatedAt: now,
+        });
+    },
+});
+export const get = query({
+    args: { agentId: v.id("agents") },
+    returns: v.union(agentDoc, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const doc = await ctx.db.get(args.agentId);
+        if (!doc || doc.orgId !== orgId)
+            return null;
+        return doc;
+    },
+});

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

@@ -0,0 +1,43 @@
+import { WorkflowManager, type WorkflowId } from "@convex-dev/workflow";
+export declare const workflow: WorkflowManager;
+export declare const start: import("convex/server").RegisteredMutation<"public", {
+    stepFunctionHandle: string;
+    totalSteps: number;
+    maxAttemptsPerStep: number;
+    kind: string;
+}, Promise<import("convex/values").GenericId<"durableJobs">>>;
+export declare const getStatus: import("convex/server").RegisteredQuery<"public", {
+    jobId: import("convex/values").GenericId<"durableJobs">;
+}, Promise<{
+    status: "running" | "completed" | "abandoned" | "cancelled";
+    cursor: number;
+    totalSteps: number;
+    lastError: string | undefined;
+    abandonedAtStep: number | undefined;
+}>>;
+export declare const cancel: import("convex/server").RegisteredMutation<"public", {
+    jobId: import("convex/values").GenericId<"durableJobs">;
+}, Promise<null>>;
+export declare const getJobInternal: import("convex/server").RegisteredQuery<"internal", {
+    jobId: import("convex/values").GenericId<"durableJobs">;
+}, Promise<{
+    cursor: number;
+    totalSteps: number;
+    maxAttemptsPerStep: number;
+    status: "running" | "completed" | "abandoned" | "cancelled";
+} | null>>;
+export declare const runStepInternal: import("convex/server").RegisteredMutation<"internal", {
+    jobId: import("convex/values").GenericId<"durableJobs">;
+    stepIndex: number;
+}, Promise<null>>;
+export declare const markAbandonedInternal: import("convex/server").RegisteredMutation<"internal", {
+    jobId: import("convex/values").GenericId<"durableJobs">;
+    stepIndex: number;
+    error: string;
+}, Promise<null>>;
+export declare const markCompletedInternal: import("convex/server").RegisteredMutation<"internal", {
+    jobId: import("convex/values").GenericId<"durableJobs">;
+}, Promise<null>>;
+export declare const durableJobWorkflowV1: import("convex/server").RegisteredMutation<"internal", import("@convex-dev/workflow").WorkflowArgs<{
+    jobId: import("convex/values").VId<import("convex/values").GenericId<"durableJobs">, "required">;
+}>, WorkflowId>;

package/dist/component/engine/durableJob.js

@@ -0,0 +1,262 @@
+import { v } from "convex/values";
+import { WorkflowManager } from "@convex-dev/workflow";
+import { components, internal } from "../_generated/api";
+import { internalMutation, internalQuery, mutation, query, } from "../_generated/server";
+import { assertSameOrg, requireOrgId } from "../lib/auth";
+// durableJobs — THE SURVIVAL CONTRACT (I1, SYNTHESE.md §5/§7): "mise en
+// pause à la frontière d'étape, rejeu déterministe, reprise, abandon après
+// N échecs." This ENVELOPS `@convex-dev/workflow` -- it does not reimplement
+// durable execution. Every real unit of work (the caller-supplied
+// `stepFunctionHandle`) runs inside its own bounded mutation call; the
+// workflow persists `cursor` (steps [0, cursor) done) between calls, so a
+// job whose TOTAL wall-clock time exceeds a single Convex action's ceiling
+// still completes -- no single call has to survive past the ceiling, only
+// the aggregate progress does.
+//
+// Contract surface (this is what a consumer -- VantagePeers/Sigma first --
+// calls; see examples/vantage-peers-long-task for a worked integration):
+//   1. `start`      -- enqueue a job of N steps, driven by a step function
+//                       the CALLER owns (created via `createFunctionHandle`
+//                       in the caller's own app). We never read the
+//                       caller's tables directly -- component isolation.
+//   2. `getStatus`  -- poll status/cursor/lastError/abandonedAtStep.
+//   3. `cancel`     -- best-effort stop (checked at the next step boundary
+//                       and by the workflow's own cancel()).
+//   4. (internal) the workflow itself is the pause/resume/replay engine:
+//       - PAUSE AT STEP BOUNDARY: each loop iteration is one workflow step;
+//         `@convex-dev/workflow` durably persists after each step returns,
+//         so the process can die between any two steps with zero data loss.
+//       - DETERMINISTIC REPLAY: `runStepInternal` is idempotent -- it
+//         no-ops for any stepIndex < job.cursor, so replaying the workflow
+//         handler after a resume never re-runs completed work.
+//       - RESUME: on restart, the workflow replays its journal up to the
+//         last completed step then continues the same in-memory loop; our
+//         `cursor` on the `durableJobs` row is the second, redundant source
+//         of truth a caller can poll without touching workflow internals.
+//       - ABANDON AFTER N: `runStepInternal` retries the caller's step
+//         function up to `maxAttemptsPerStep` times INSIDE one workflow
+//         step (not via workflow-level retry, which does not apply to
+//         mutations); only once attempts are exhausted does the step throw,
+//         which the workflow handler catches and turns into
+//         `status: "abandoned"` with `abandonedAtStep` + `lastError`.
+//
+// Versioned workflow discipline (workflow#35, I0 §7.1) -- same as
+// `engine/workflows.ts:sessionWorkflowV1`: never edit `durableJobWorkflowV1`
+// in place once jobs reference it; ship `...V2` and drain v1 first.
+const CURRENT_WORKFLOW_VERSION = "v1";
+export const workflow = new WorkflowManager(components.workflow);
+// ---------------------------------------------------------------------
+// PUBLIC CONTRACT
+// ---------------------------------------------------------------------
+export const start = mutation({
+    args: {
+        kind: v.string(),
+        stepFunctionHandle: v.string(),
+        totalSteps: v.number(),
+        maxAttemptsPerStep: v.number(),
+    },
+    returns: v.id("durableJobs"),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        if (!Number.isInteger(args.totalSteps) || args.totalSteps <= 0) {
+            throw new Error("Validation: totalSteps must be a positive integer");
+        }
+        if (!Number.isInteger(args.maxAttemptsPerStep) ||
+            args.maxAttemptsPerStep <= 0) {
+            throw new Error("Validation: maxAttemptsPerStep must be a positive integer");
+        }
+        if (args.stepFunctionHandle.length === 0) {
+            throw new Error("Validation: stepFunctionHandle must not be empty");
+        }
+        const now = Date.now();
+        const jobId = await ctx.db.insert("durableJobs", {
+            orgId,
+            kind: args.kind,
+            stepFunctionHandle: args.stepFunctionHandle,
+            totalSteps: args.totalSteps,
+            maxAttemptsPerStep: args.maxAttemptsPerStep,
+            cursor: 0,
+            status: "running",
+            workflowVersion: CURRENT_WORKFLOW_VERSION,
+            createdAt: now,
+            updatedAt: now,
+        });
+        const workflowId = await workflow.start(ctx, internal.engine.durableJob.durableJobWorkflowV1, { jobId });
+        await ctx.db.patch(jobId, { workflowId });
+        return jobId;
+    },
+});
+export const getStatus = query({
+    args: { jobId: v.id("durableJobs") },
+    returns: v.object({
+        status: v.union(v.literal("running"), v.literal("completed"), v.literal("abandoned"), v.literal("cancelled")),
+        cursor: v.number(),
+        totalSteps: v.number(),
+        lastError: v.optional(v.string()),
+        abandonedAtStep: v.optional(v.number()),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const job = await ctx.db.get(args.jobId);
+        assertSameOrg(orgId, job, "Job not found");
+        return {
+            status: job.status,
+            cursor: job.cursor,
+            totalSteps: job.totalSteps,
+            lastError: job.lastError,
+            abandonedAtStep: job.abandonedAtStep,
+        };
+    },
+});
+export const cancel = mutation({
+    args: { jobId: v.id("durableJobs") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const job = await ctx.db.get(args.jobId);
+        assertSameOrg(orgId, job, "Job not found");
+        if (job.status !== "running")
+            return null;
+        await ctx.db.patch(args.jobId, {
+            status: "cancelled",
+            updatedAt: Date.now(),
+        });
+        if (job.workflowId) {
+            await workflow.cancel(ctx, job.workflowId);
+        }
+        return null;
+    },
+});
+// ---------------------------------------------------------------------
+// INTERNAL — server-to-server only, invoked by the workflow's own steps.
+// The workflow runs with no end-user identity: every handler below scopes
+// strictly by the orgId already recorded on the `durableJobs` row, never a
+// client-supplied one.
+// ---------------------------------------------------------------------
+export const getJobInternal = internalQuery({
+    args: { jobId: v.id("durableJobs") },
+    returns: v.union(v.object({
+        cursor: v.number(),
+        totalSteps: v.number(),
+        maxAttemptsPerStep: v.number(),
+        status: v.union(v.literal("running"), v.literal("completed"), v.literal("abandoned"), v.literal("cancelled")),
+    }), v.null()),
+    handler: async (ctx, args) => {
+        const job = await ctx.db.get(args.jobId);
+        if (!job)
+            return null;
+        return {
+            cursor: job.cursor,
+            totalSteps: job.totalSteps,
+            maxAttemptsPerStep: job.maxAttemptsPerStep,
+            status: job.status,
+        };
+    },
+});
+// The one real unit of work per step-boundary. DETERMINISTIC REPLAY GUARD:
+// no-ops for any stepIndex already covered by job.cursor, so a workflow
+// resume (journal replay after a kill mid-run) never re-executes the
+// caller's step function for completed steps. ABANDON AFTER N: retries the
+// caller's step function up to `maxAttemptsPerStep` times before throwing
+// (throwing is what the workflow handler below turns into "abandoned").
+export const runStepInternal = internalMutation({
+    args: { jobId: v.id("durableJobs"), stepIndex: v.number() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const job = await ctx.db.get(args.jobId);
+        if (!job)
+            throw new Error("Job not found");
+        if (job.status === "cancelled")
+            return null;
+        if (args.stepIndex < job.cursor) {
+            // Already-completed step replayed by a resumed workflow -- no-op.
+            return null;
+        }
+        let lastError;
+        for (let attempt = 1; attempt <= job.maxAttemptsPerStep; attempt++) {
+            try {
+                await ctx.runMutation(job.stepFunctionHandle, { orgId: job.orgId, jobId: args.jobId, stepIndex: args.stepIndex });
+                await ctx.db.patch(args.jobId, {
+                    cursor: args.stepIndex + 1,
+                    updatedAt: Date.now(),
+                });
+                return null;
+            }
+            catch (err) {
+                lastError = err;
+            }
+        }
+        throw lastError instanceof Error
+            ? lastError
+            : new Error(String(lastError));
+    },
+});
+export const markAbandonedInternal = internalMutation({
+    args: { jobId: v.id("durableJobs"), stepIndex: v.number(), error: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const job = await ctx.db.get(args.jobId);
+        if (!job || job.status !== "running")
+            return null;
+        await ctx.db.patch(args.jobId, {
+            status: "abandoned",
+            abandonedAtStep: args.stepIndex,
+            lastError: args.error,
+            updatedAt: Date.now(),
+        });
+        return null;
+    },
+});
+export const markCompletedInternal = internalMutation({
+    args: { jobId: v.id("durableJobs") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const job = await ctx.db.get(args.jobId);
+        if (!job || job.status !== "running")
+            return null;
+        await ctx.db.patch(args.jobId, {
+            status: "completed",
+            updatedAt: Date.now(),
+        });
+        return null;
+    },
+});
+// durableJobWorkflowV1 -- the pause/resume/replay engine. One loop
+// iteration == one workflow step == one durability boundary: `step.
+// runMutation` returns only after `@convex-dev/workflow` has persisted the
+// journal entry, so a process kill between any two iterations loses zero
+// progress. On resume the workflow replays already-journaled steps from
+// its own history (no caller-visible effect, since runStepInternal is
+// idempotent below job.cursor) and continues the loop from where it left
+// off.
+export const durableJobWorkflowV1 = workflow.define({
+    args: { jobId: v.id("durableJobs") },
+    returns: v.null(),
+    handler: async (step, args) => {
+        const job = await step.runQuery(internal.engine.durableJob.getJobInternal, {
+            jobId: args.jobId,
+        });
+        if (!job || job.status !== "running")
+            return null;
+        for (let i = job.cursor; i < job.totalSteps; i++) {
+            try {
+                await step.runMutation(internal.engine.durableJob.runStepInternal, {
+                    jobId: args.jobId,
+                    stepIndex: i,
+                });
+            }
+            catch (err) {
+                await step.runMutation(internal.engine.durableJob.markAbandonedInternal, {
+                    jobId: args.jobId,
+                    stepIndex: i,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return null;
+            }
+        }
+        await step.runMutation(internal.engine.durableJob.markCompletedInternal, {
+            jobId: args.jobId,
+        });
+        return null;
+    },
+});

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

@@ -0,0 +1,12 @@
+export declare const resolveManifest: import("convex/server").RegisteredQuery<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+}, Promise<{
+    agentId: import("convex/values").GenericId<"agents">;
+    name: string;
+    instructions: string;
+    model: string;
+    toolApprovals: {
+        toolName: string;
+        approval: "always" | "once" | "never";
+    }[];
+}>>;

package/dist/component/engine/resolvers.js

@@ -0,0 +1,50 @@
+import { v } from "convex/values";
+import { query } from "../_generated/server";
+import { assertSameOrg, requireOrgId } from "../lib/auth";
+// resolveManifest — the dynamic resolver (eve parity:
+// `dynamicInstructions`/`dynamicSkills`/`dynamicTools`,
+// packages/eve/src/compiler/manifest.ts:722-725). Produced FRESH from the
+// aggregate on every call, never compiled/cached — an agent edited between
+// sessions is visible on the very next `session.started`/`turn.started`
+// call with zero redeploy. `sessions.start` and `sessions.sendTurn` both
+// call this at their respective boundaries (ALLOWED_DYNAMIC_INSTRUCTION_
+// EVENTS, dynamic-tool-definition.ts:40-46).
+//
+// T2-QUINQUIES scope note: `toolApprovals` is included (in scope per
+// brief). `skills`/`connections` are NOT (out of scope for this pass — see
+// component/schema.ts SCOPE note); this resolver returns only what the
+// component boundary currently owns.
+export const resolveManifest = query({
+    args: { sessionId: v.id("sessions") },
+    returns: v.object({
+        agentId: v.id("agents"),
+        name: v.string(),
+        instructions: v.string(),
+        model: v.string(),
+        toolApprovals: v.array(v.object({
+            toolName: v.string(),
+            approval: v.union(v.literal("always"), v.literal("once"), v.literal("never")),
+        })),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = await requireOrgId(ctx);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        const agent = await ctx.db.get(session.agentId);
+        assertSameOrg(orgId, agent, "Agent not found");
+        const toolApprovals = await ctx.db
+            .query("toolApprovals")
+            .withIndex("by_org_agent", (q) => q.eq("orgId", orgId).eq("agentId", session.agentId))
+            .collect();
+        return {
+            agentId: agent._id,
+            name: agent.name,
+            instructions: agent.instructions,
+            model: agent.model,
+            toolApprovals: toolApprovals.map((t) => ({
+                toolName: t.toolName,
+                approval: t.approval,
+            })),
+        };
+    },
+});

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

@@ -0,0 +1,36 @@
+export declare const start: import("convex/server").RegisteredMutation<"public", {
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<import("convex/values").GenericId<"sessions">>>;
+export declare const sendTurn: import("convex/server").RegisteredMutation<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+    input: string;
+}, Promise<null>>;
+export declare const appendReasoning: import("convex/server").RegisteredMutation<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+    chunk: string;
+}, Promise<null>>;
+export declare const requestToolCall: import("convex/server").RegisteredMutation<"public", {
+    toolName: string;
+    sessionId: import("convex/values").GenericId<"sessions">;
+    argsJson: string;
+}, Promise<{
+    authorized: boolean;
+    approvalPending: boolean;
+}>>;
+export declare const completeToolCall: import("convex/server").RegisteredMutation<"public", {
+    toolName: string;
+    sessionId: import("convex/values").GenericId<"sessions">;
+    resultJson: string;
+}, Promise<null>>;
+export declare const completeTurn: import("convex/server").RegisteredMutation<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+}, Promise<null>>;
+export declare const listEvents: import("convex/server").RegisteredQuery<"public", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+}, 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";
+    payload: string | undefined;
+    createdAt: number;
+}[]>>;