@vantageos/agent-engine 0.3.0-alpha.0 → 0.4.0-alpha.0

package/README.md

@@ -106,7 +106,7 @@ components.agentEngine.engine.resolvers.resolveManifest({
 components.agentEngine.engine.sessions.start({
   orgId, agentId, createdBy,
 }) -> { sessionId: string /* the world runId */, workflowId: string }
-// 0.3.0: every `sessionId` below IS that runId (string); an unknown, legacy,
+// 0.3.0: every `sessionId` below IS that runId (string); an unknown,
 // cross-org or non-session id is refused as "Session not found".
 components.agentEngine.engine.sessions.sendTurn({
   orgId, sessionId, input,

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

@@ -1,3 +1,11 @@
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
 import type * as engine_agents from "../engine/agents.js";
 import type * as engine_awaitEventTimeout from "../engine/awaitEventTimeout.js";
 import type * as engine_connections from "../engine/connections.js";
@@ -20,7 +28,7 @@ import type * as lib_auth from "../lib/auth.js";
 import type * as lib_connectionSecret from "../lib/connectionSecret.js";
 import type * as testFixtures_callerSteps from "../testFixtures/callerSteps.js";
 import type * as testFixtures_delegationDemoWorkflow from "../testFixtures/delegationDemoWorkflow.js";
-import type * as testFixtures_legacyBind from "../testFixtures/legacyBind.js";
+import type * as testFixtures_runBinding from "../testFixtures/runBinding.js";
 import type * as testFixtures_sandboxDemoWorkflow from "../testFixtures/sandboxDemoWorkflow.js";
 import type * as testFixtures_vpTool from "../testFixtures/vpTool.js";
 import type * as testFixtures_wakeupDemoWorkflow from "../testFixtures/wakeupDemoWorkflow.js";
@@ -49,13 +57,29 @@ declare const fullApi: ApiFromModules<{
     "lib/connectionSecret": typeof lib_connectionSecret;
     "testFixtures/callerSteps": typeof testFixtures_callerSteps;
     "testFixtures/delegationDemoWorkflow": typeof testFixtures_delegationDemoWorkflow;
-    "testFixtures/legacyBind": typeof testFixtures_legacyBind;
+    "testFixtures/runBinding": typeof testFixtures_runBinding;
     "testFixtures/sandboxDemoWorkflow": typeof testFixtures_sandboxDemoWorkflow;
     "testFixtures/vpTool": typeof testFixtures_vpTool;
     "testFixtures/wakeupDemoWorkflow": typeof testFixtures_wakeupDemoWorkflow;
     "testFixtures/wakeupWork": typeof testFixtures_wakeupWork;
 }>;
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
 export declare const api: FilterApi<typeof fullApi, FunctionReference<any, "public">>;
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
 export declare const internal: FilterApi<typeof fullApi, FunctionReference<any, "internal">>;
 export declare const components: {
     workflow: import("@convex-dev/workflow/_generated/component.js").ComponentApi<"workflow">;

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

@@ -1,4 +1,23 @@
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
 import type { FunctionReference } from "convex/server";
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
 export type ComponentApi<Name extends string | undefined = string | undefined> = {
     engine: {
         agents: {
@@ -37,8 +56,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         };
         awaitEventTimeout: {
             cancel: FunctionReference<"mutation", "internal", {
+                hookId: string;
                 orgId: string;
-                timeoutRowId: string;
             }, null, Name>;
             schedule: FunctionReference<"mutation", "internal", {
                 awaitedEventName: string;

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

@@ -1,7 +1,45 @@
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
 import type { DataModelFromSchemaDefinition, DocumentByName, TableNamesInDataModel, SystemTableNames } from "convex/server";
 import type { GenericId } from "convex/values";
 import schema from "../schema.js";
+/**
+ * The names of all of your Convex tables.
+ */
 export type TableNames = TableNamesInDataModel<DataModel>;
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
 export type Doc<TableName extends TableNames> = DocumentByName<DataModel, TableName>;
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
 export type Id<TableName extends TableNames | SystemTableNames> = GenericId<TableName>;
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
 export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

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

@@ -1,14 +1,120 @@
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
 import type { ActionBuilder, HttpActionBuilder, MutationBuilder, QueryBuilder, GenericActionCtx, GenericMutationCtx, GenericQueryCtx, GenericDatabaseReader, GenericDatabaseWriter } from "convex/server";
 import type { DataModel } from "./dataModel.js";
+/**
+ * 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 declare const query: QueryBuilder<DataModel, "public">;
+/**
+ * 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 declare const internalQuery: QueryBuilder<DataModel, "internal">;
+/**
+ * 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 declare const mutation: MutationBuilder<DataModel, "public">;
+/**
+ * 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 declare const internalMutation: MutationBuilder<DataModel, "internal">;
+/**
+ * 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 declare const action: ActionBuilder<DataModel, "public">;
+/**
+ * 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 declare const internalAction: ActionBuilder<DataModel, "internal">;
+/**
+ * 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 declare const httpAction: HttpActionBuilder;
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
 export type QueryCtx = GenericQueryCtx<DataModel>;
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
 export type MutationCtx = GenericMutationCtx<DataModel>;
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
 export type ActionCtx = GenericActionCtx<DataModel>;
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
 export type DatabaseReader = GenericDatabaseReader<DataModel>;
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
 export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

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

@@ -23,10 +23,10 @@ export declare const get: import("convex/server").RegisteredQuery<"public", {
     maxInputTokensPerSession?: number | false | undefined;
     name: string;
     orgId: string;
-    status: "draft" | "live" | "archived";
-    createdAt: number;
-    updatedAt: number;
     instructions: string;
     model: string;
+    status: "draft" | "live" | "archived";
     createdBy: string;
+    createdAt: number;
+    updatedAt: number;
 } | null>>;

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

@@ -1,13 +1,14 @@
 export declare const schedule: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
-    sessionId: string;
     awaitedEventName: string;
+    sessionId: string;
     timeoutMs: number;
-}, Promise<import("convex/values").GenericId<"awaitEventTimeouts">>>;
+}, Promise<string>>;
 export declare const cancel: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
-    timeoutRowId: import("convex/values").GenericId<"awaitEventTimeouts">;
+    hookId: string;
 }, Promise<null>>;
-export declare const fire: import("convex/server").RegisteredMutation<"internal", {
-    timeoutRowId: import("convex/values").GenericId<"awaitEventTimeouts">;
+export declare const expire: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    hookId: string;
 }, Promise<null>>;

package/dist/component/engine/awaitEventTimeout.js

@@ -1,9 +1,9 @@
 import { v } from "convex/values";
-import { internal } from "../_generated/api.js";
 import { internalMutation, mutation } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 import { insertEvent, loadSessionRun } from "./sessions.js";
-import { findRunIdByCorrelation, legacyCorrelationId, legacySessionOf, loadRun, } from "./world.js";
+import { appendEventCore, loadRun } from "./world.js";
+const NOT_FOUND = "Timeout not found";
 export const schedule = mutation({
     args: {
         orgId: v.string(),
@@ -11,62 +11,79 @@ export const schedule = mutation({
         awaitedEventName: v.string(),
         timeoutMs: v.number(),
     },
-    returns: v.id("awaitEventTimeouts"),
+    returns: v.string(),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
         const run = await loadSessionRun(ctx, orgId, args.sessionId);
-        const legacy = await legacySessionOf(ctx, run, orgId);
-        if (args.timeoutMs <= 0) {
+        if (!(args.timeoutMs > 0)) {
             throw new Error("Validation: timeoutMs must be > 0");
         }
-        const timeoutRowId = await ctx.db.insert("awaitEventTimeouts", {
+        const hookId = `hook_${crypto.randomUUID()}`;
+        await appendEventCore(ctx, {
             orgId,
             runId: run.runId,
-            sessionId: legacy?._id,
-            awaitedEventName: args.awaitedEventName,
-            deadlineAt: Date.now() + args.timeoutMs,
+            eventType: "hook_created",
+            hookId,
+            dataJson: JSON.stringify({
+                token: `tok_${crypto.randomUUID()}`,
+                expiresAt: Date.now() + args.timeoutMs,
+                awaitedEventName: args.awaitedEventName,
+            }),
         });
-        const scheduledFunctionId = await ctx.scheduler.runAfter(args.timeoutMs, internal.engine.awaitEventTimeout.fire, { timeoutRowId });
-        await ctx.db.patch(timeoutRowId, { scheduledFunctionId });
-        return timeoutRowId;
+        return hookId;
     },
 });
 export const cancel = mutation({
-    args: { orgId: v.string(), timeoutRowId: v.id("awaitEventTimeouts") },
+    args: { orgId: v.string(), hookId: v.string() },
     returns: v.null(),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
-        const row = await ctx.db.get(args.timeoutRowId);
-        assertSameOrg(orgId, row, "Timeout not found");
-        if (!row.firedAt && !row.cancelledAt && row.scheduledFunctionId) {
-            await ctx.scheduler.cancel(row.scheduledFunctionId);
-            await ctx.db.patch(args.timeoutRowId, { cancelledAt: Date.now() });
+        const hook = await ctx.db
+            .query("worldHooks")
+            .withIndex("by_org_hook", (q) => q.eq("orgId", orgId).eq("hookId", args.hookId))
+            .unique();
+        assertSameOrg(orgId, hook, NOT_FOUND);
+        if (hook.expiresAt === undefined) {
+            throw new Error(NOT_FOUND);
         }
+        await appendEventCore(ctx, {
+            orgId,
+            runId: hook.runId,
+            eventType: "hook_disposed",
+            hookId: args.hookId,
+            dataJson: "{}",
+        });
         return null;
     },
 });
-export const fire = internalMutation({
-    args: { timeoutRowId: v.id("awaitEventTimeouts") },
+export const expire = internalMutation({
+    args: { orgId: v.string(), hookId: v.string() },
     returns: v.null(),
     handler: async (ctx, args) => {
-        const row = await ctx.db.get(args.timeoutRowId);
-        if (!row || row.firedAt || row.cancelledAt) {
+        const hook = await ctx.db
+            .query("worldHooks")
+            .withIndex("by_org_hook", (q) => q.eq("orgId", args.orgId).eq("hookId", args.hookId))
+            .unique();
+        if (!hook ||
+            hook.status !== "pending" ||
+            hook.awaitedEventName === undefined ||
+            hook.expiresAt === undefined) {
             return null;
         }
-        await ctx.db.patch(args.timeoutRowId, { firedAt: Date.now() });
-        let runId = row.runId;
-        if (runId === undefined && row.sessionId !== undefined) {
-            runId =
-                (await findRunIdByCorrelation(ctx, row.orgId, legacyCorrelationId("sessions", row.sessionId))) ?? undefined;
-        }
-        if (runId === undefined)
-            return null;
-        const run = await loadRun(ctx, row.orgId, runId, "sessions", "Session not found");
+        const run = await loadRun(ctx, args.orgId, hook.runId, "session", "Session not found");
         await insertEvent(ctx, {
-            orgId: row.orgId,
+            orgId: args.orgId,
             run,
             name: "sandbox.timeout",
-            payload: JSON.stringify({ awaitedEventName: row.awaitedEventName }),
+            payload: JSON.stringify({ awaitedEventName: hook.awaitedEventName }),
+        });
+        await ctx.db.patch(hook._id, { scheduledFunctionId: undefined });
+        await appendEventCore(ctx, {
+            orgId: args.orgId,
+            runId: hook.runId,
+            eventType: "hook_disposed",
+            hookId: args.hookId,
+            dataJson: "{}",
         });
         return null;
     },

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

@@ -24,10 +24,10 @@ export declare const listSubagents: import("convex/server").RegisteredQuery<"pub
 export declare const delegateToSubagent: import("convex/server").RegisteredAction<"public", {
     payload?: string | undefined;
     orgId: string;
-    workflowId: string;
-    awaitedEventName: string;
     scope: string;
     reason: string;
+    workflowId: string;
+    awaitedEventName: string;
     cost: number;
     subagentId: import("convex/values").GenericId<"subagents">;
     workFunctionHandle: string;
@@ -35,11 +35,11 @@ export declare const delegateToSubagent: import("convex/server").RegisteredActio
 export declare const invokeAgentClone: import("convex/server").RegisteredAction<"public", {
     payload?: string | undefined;
     orgId: string;
-    workflowId: string;
     agentId: import("convex/values").GenericId<"agents">;
-    awaitedEventName: string;
     scope: string;
     reason: string;
+    workflowId: string;
+    awaitedEventName: string;
     cost: number;
     workFunctionHandle: string;
     viaAgentTool: boolean;
@@ -61,15 +61,15 @@ export declare const getAgentInternal: import("convex/server").RegisteredQuery<"
 } | null>>;
 export declare const recordDelegationStartInternal: import("convex/server").RegisteredMutation<"internal", {
     orgId: string;
-    workflowId: string;
     toolName: string;
+    workflowId: string;
     awaitedEventName: string;
     parentAgentId: import("convex/values").GenericId<"agents">;
     childAgentId: import("convex/values").GenericId<"agents">;
 }, Promise<import("convex/values").GenericId<"delegationRuns">>>;
 export declare const recordCloneStartInternal: import("convex/server").RegisteredMutation<"internal", {
     orgId: string;
-    workflowId: string;
     agentId: import("convex/values").GenericId<"agents">;
+    workflowId: string;
     awaitedEventName: string;
 }, Promise<import("convex/values").GenericId<"agentCloneRuns">>>;

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

@@ -3,10 +3,10 @@ type JobRunStatus = "running" | "completed" | "abandoned" | "cancelled";
 export declare const workflow: WorkflowManager;
 export declare const start: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
+    kind: string;
     stepFunctionHandle: string;
     totalSteps: number;
     maxAttemptsPerStep: number;
-    kind: string;
 }, Promise<string>>;
 export declare const getStatus: import("convex/server").RegisteredQuery<"public", {
     orgId: string;
@@ -22,29 +22,6 @@ export declare const cancel: import("convex/server").RegisteredMutation<"public"
     orgId: string;
     jobId: string;
 }, 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>;
 export declare const getJobInternalV2: import("convex/server").RegisteredQuery<"internal", {
     orgId: string;
     runId: string;
@@ -56,14 +33,14 @@ export declare const getJobInternalV2: import("convex/server").RegisteredQuery<"
 } | null>>;
 export declare const runStepInternalV2: import("convex/server").RegisteredMutation<"internal", {
     orgId: string;
-    stepIndex: number;
     runId: string;
+    stepIndex: number;
 }, Promise<null>>;
 export declare const markAbandonedInternalV2: import("convex/server").RegisteredMutation<"internal", {
     orgId: string;
-    stepIndex: number;
-    runId: string;
     error: string;
+    runId: string;
+    stepIndex: number;
 }, Promise<null>>;
 export declare const markCompletedInternalV2: import("convex/server").RegisteredMutation<"internal", {
     orgId: string;