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

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: {

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.js

@@ -3,7 +3,7 @@ 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 { findRunIdByCorrelation, legacyCorrelationId, loadRun, } from "./world.js";
 export const schedule = mutation({
     args: {
         orgId: v.string(),
@@ -15,14 +15,12 @@ export const schedule = mutation({
     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) {
             throw new Error("Validation: timeoutMs must be > 0");
         }
         const timeoutRowId = await ctx.db.insert("awaitEventTimeouts", {
             orgId,
             runId: run.runId,
-            sessionId: legacy?._id,
             awaitedEventName: args.awaitedEventName,
             deadlineAt: Date.now() + args.timeoutMs,
         });
@@ -57,11 +55,11 @@ export const fire = internalMutation({
         let runId = row.runId;
         if (runId === undefined && row.sessionId !== undefined) {
             runId =
-                (await findRunIdByCorrelation(ctx, row.orgId, legacyCorrelationId("sessions", row.sessionId))) ?? undefined;
+                (await findRunIdByCorrelation(ctx, row.orgId, legacyCorrelationId("session", 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, row.orgId, runId, "session", "Session not found");
         await insertEvent(ctx, {
             orgId: row.orgId,
             run,

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

@@ -47,8 +47,8 @@ export declare const listByAgent: import("convex/server").RegisteredQuery<"publi
 }[]>>;
 export declare const requestAuthorization: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
-    workflowId: string;
     awaitedEventName: string;
+    workflowId: string;
     connectionId: import("convex/values").GenericId<"connections">;
     url: string;
     userCode: string;

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;
     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;
     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;
     awaitedEventName: string;
+    workflowId: 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">;
     awaitedEventName: string;
+    workflowId: 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;
+    stepIndex: number;
 }, Promise<null>>;
 export declare const markCompletedInternalV2: import("convex/server").RegisteredMutation<"internal", {
     orgId: string;