@vantageos/agent-engine 0.1.0-alpha.8 → 0.3.0-alpha.1

package/README.md

@@ -33,6 +33,16 @@ consuming app.
 npm install @vantageos/agent-engine
 ```
 
+### What ships in the package
+
+The published tarball is `dist/` (compiled JS + `.d.ts`), `README.md`,
+`LICENSE`. `dist/component/testFixtures/**` is deliberately excluded
+(`package.json` `"files"` negation `"!dist/component/testFixtures"`) — it is
+test-only demo workflow code used by this repo's own component-packaging
+tests, never part of the public `exports` (`./convex.config` and
+`./_generated/component.js`), and not a documented consumer API. No file is
+published without a stated reason.
+
 ## Quickstart
 
 Register the component in your app's `convex/convex.config.ts`:
@@ -95,7 +105,9 @@ components.agentEngine.engine.resolvers.resolveManifest({
 
 components.agentEngine.engine.sessions.start({
   orgId, agentId, createdBy,
-}) -> { sessionId: Id<"sessions">, workflowId: string }
+}) -> { sessionId: string /* the world runId */, workflowId: string }
+// 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,
 }) -> null
@@ -111,9 +123,13 @@ components.agentEngine.engine.sessions.completeToolCall({
 components.agentEngine.engine.sessions.completeTurn({
   orgId, sessionId,
 }) -> null
+components.agentEngine.engine.sessions.end({
+  orgId, sessionId, outcome: "completed"|"cancelled",
+}) -> null
 components.agentEngine.engine.sessions.listEvents({
   orgId, sessionId,
-}) -> sessionEvent[]
+}) -> { _id /* journal eventId */, _creationTime /* event createdAt, ms */,
+        name, payload?, createdAt }[]   (read from the world journal)
 
 components.agentEngine.engine.toolApprovals.respond({
   orgId, sessionId, toolName,
@@ -124,16 +140,16 @@ components.agentEngine.engine.toolApprovals.respond({
 components.agentEngine.engine.wakeup.enqueue({
   orgId, agentId, mandateScope, cost, reason,
   workFunctionHandle, workflowId, awaitedEventName,
-}) -> Id<"wakeableWork">  (action)
-components.agentEngine.engine.wakeup.cancel({ orgId, wakeableWorkId }) -> null
+}) -> string  (action; the world-queue messageId)
+components.agentEngine.engine.wakeup.cancel({ orgId, messageId }) -> null
 components.agentEngine.engine.wakeup.getStatus({
-  orgId, wakeableWorkId,
-}) -> { status, resultSummary?, ... }
+  orgId, messageId,
+}) -> { status: "pending" | "delivered" | "failed" }
 
 components.agentEngine.engine.durableJob.start({
   orgId, kind, stepFunctionHandle, totalSteps, maxAttemptsPerStep,
-}) -> Id<"durableJobs">
-components.agentEngine.engine.durableJob.getStatus({ orgId, jobId })
+}) -> string  (the world runId)
+components.agentEngine.engine.durableJob.getStatus({ orgId, jobId /* runId */ })
   -> { status, cursor, totalSteps, lastError?, abandonedAtStep? }
 components.agentEngine.engine.durableJob.cancel({ orgId, jobId }) -> null
 
@@ -242,6 +258,15 @@ calling in. Every document lookup by id is checked against the caller's own
 `orgId` before being returned or mutated; a cross-org read or write is
 refused the same way a not-found row would be.
 
+## Dependency pins
+
+`ai` is pinned to v6 (`6.0.35`) in the root package; any other tree that declares `ai` must use the same major (world-convex declares none today).
+
+Two sub-packages (`first-orchestrator/`, `scheduling-specialist/`) keep `ai ^7.0.58` because
+eve@0.44.3 peers `ai ^7.0.58` (no eve release peers v6); each runs in its own process with its own
+install, sharing no dependency tree with root or world-convex. Everywhere else the v6 pin stands;
+`scripts/vitestScope.test.ts` enforces it.
+
 ## Requirements
 
 - Convex `^1.42`

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

@@ -8,21 +8,27 @@
  */
 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";
 import type * as engine_delegation from "../engine/delegation.js";
 import type * as engine_directory from "../engine/directory.js";
 import type * as engine_durableJob from "../engine/durableJob.js";
-import type * as engine_habits from "../engine/habits.js";
 import type * as engine_mandates from "../engine/mandates.js";
+import type * as engine_queue from "../engine/queue.js";
 import type * as engine_resolvers from "../engine/resolvers.js";
 import type * as engine_sandboxCallback from "../engine/sandboxCallback.js";
+import type * as engine_sandboxConfigProvider from "../engine/sandboxConfigProvider.js";
 import type * as engine_sessions from "../engine/sessions.js";
+import type * as engine_streams from "../engine/streams.js";
 import type * as engine_toolApprovals from "../engine/toolApprovals.js";
 import type * as engine_vpConnection from "../engine/vpConnection.js";
 import type * as engine_wakeup from "../engine/wakeup.js";
 import type * as engine_workflows from "../engine/workflows.js";
+import type * as engine_world from "../engine/world.js";
 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_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";
@@ -31,21 +37,27 @@ import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server
 declare const fullApi: ApiFromModules<{
     "engine/agents": typeof engine_agents;
     "engine/awaitEventTimeout": typeof engine_awaitEventTimeout;
+    "engine/connections": typeof engine_connections;
     "engine/delegation": typeof engine_delegation;
     "engine/directory": typeof engine_directory;
     "engine/durableJob": typeof engine_durableJob;
-    "engine/habits": typeof engine_habits;
     "engine/mandates": typeof engine_mandates;
+    "engine/queue": typeof engine_queue;
     "engine/resolvers": typeof engine_resolvers;
     "engine/sandboxCallback": typeof engine_sandboxCallback;
+    "engine/sandboxConfigProvider": typeof engine_sandboxConfigProvider;
     "engine/sessions": typeof engine_sessions;
+    "engine/streams": typeof engine_streams;
     "engine/toolApprovals": typeof engine_toolApprovals;
     "engine/vpConnection": typeof engine_vpConnection;
     "engine/wakeup": typeof engine_wakeup;
     "engine/workflows": typeof engine_workflows;
+    "engine/world": typeof engine_world;
     "lib/auth": typeof lib_auth;
+    "lib/connectionSecret": typeof lib_connectionSecret;
     "testFixtures/callerSteps": typeof testFixtures_callerSteps;
     "testFixtures/delegationDemoWorkflow": typeof testFixtures_delegationDemoWorkflow;
+    "testFixtures/runBinding": typeof testFixtures_runBinding;
     "testFixtures/sandboxDemoWorkflow": typeof testFixtures_sandboxDemoWorkflow;
     "testFixtures/vpTool": typeof testFixtures_vpTool;
     "testFixtures/wakeupDemoWorkflow": typeof testFixtures_wakeupDemoWorkflow;
@@ -76,6 +88,5 @@ export declare const components: {
     agent: import("@convex-dev/agent/_generated/component.js").ComponentApi<"agent">;
     rateLimiter: import("@convex-dev/rate-limiter/_generated/component.js").ComponentApi<"rateLimiter">;
     shardedCounter: import("@convex-dev/sharded-counter/_generated/component.js").ComponentApi<"shardedCounter">;
-    crons: import("@convex-dev/crons/_generated/component.js").ComponentApi<"crons">;
 };
 export {};

package/dist/component/_generated/api.js

@@ -1,30 +1,5 @@
-/* eslint-disable */
-/**
- * Generated `api` utility.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
 import { anyApi, componentsGeneric } from "convex/server";
 const fullApi = anyApi;
-/**
- * A utility for referencing Convex functions in your app's public API.
- *
- * Usage:
- * ```js
- * const myFunctionReference = api.myModule.myFunction;
- * ```
- */
 export const api = anyApi;
-/**
- * A utility for referencing Convex functions in your app's internal API.
- *
- * Usage:
- * ```js
- * const myFunctionReference = internal.myModule.myFunction;
- * ```
- */
 export const internal = anyApi;
 export const components = componentsGeneric();

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

@@ -66,6 +66,81 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 timeoutMs: number;
             }, string, Name>;
         };
+        connections: {
+            completeAuthorization: FunctionReference<"mutation", "internal", {
+                connectionAuthorizationId: string;
+                encryptionKeyBase64?: string;
+                orgId: string;
+                outcome: "authorized" | "denied";
+                resultSummary?: string;
+                secretPlaintext?: string;
+            }, {
+                outcome: "woke" | "already-resolved";
+            }, Name>;
+            create: FunctionReference<"mutation", "internal", {
+                agentId: string;
+                authMode: "app-token" | "user-oauth" | "none" | "header";
+                encryptionKeyBase64?: string;
+                name: string;
+                orgId: string;
+                secretPlaintext?: string;
+                serverConfig: string;
+                type: "mcp" | "openapi";
+            }, string, Name>;
+            get: FunctionReference<"query", "internal", {
+                connectionId: string;
+                orgId: string;
+            }, {
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                authMode: "app-token" | "user-oauth" | "none" | "header";
+                createdAt: number;
+                hasSecret: boolean;
+                name: string;
+                orgId: string;
+                principalType: "app" | "user";
+                serverConfig: string;
+                status: "active" | "pending_authorization" | "error";
+                type: "mcp" | "openapi";
+                updatedAt: number;
+            }, Name>;
+            getAuthorizationStatus: FunctionReference<"query", "internal", {
+                connectionAuthorizationId: string;
+                orgId: string;
+            }, {
+                resultSummary?: string;
+                status: "pending" | "authorized" | "denied";
+                url: string;
+                userCode: string;
+            }, Name>;
+            listByAgent: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                authMode: "app-token" | "user-oauth" | "none" | "header";
+                createdAt: number;
+                hasSecret: boolean;
+                name: string;
+                orgId: string;
+                principalType: "app" | "user";
+                serverConfig: string;
+                status: "active" | "pending_authorization" | "error";
+                type: "mcp" | "openapi";
+                updatedAt: number;
+            }>, Name>;
+            requestAuthorization: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                connectionId: string;
+                orgId: string;
+                url: string;
+                userCode: string;
+                workflowId: string;
+            }, string, Name>;
+        };
         delegation: {
             declareSubagent: FunctionReference<"mutation", "internal", {
                 childAgentId: string;
@@ -146,75 +221,6 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 totalSteps: number;
             }, string, Name>;
         };
-        habits: {
-            create: FunctionReference<"mutation", "internal", {
-                agentId: string;
-                cronExpression: string;
-                name: string;
-                orgId: string;
-                prompt: string;
-            }, string, Name>;
-            disable: FunctionReference<"mutation", "internal", {
-                habitId: string;
-                orgId: string;
-            }, null, Name>;
-            enable: FunctionReference<"mutation", "internal", {
-                habitId: string;
-                orgId: string;
-            }, null, Name>;
-            get: FunctionReference<"query", "internal", {
-                habitId: string;
-                orgId: string;
-            }, {
-                _creationTime: number;
-                _id: string;
-                agentId: string;
-                createdAt: number;
-                cronExpression: string;
-                cronJobId?: string;
-                enabled: boolean;
-                lastRunAt?: number;
-                name: string;
-                orgId: string;
-                prompt: string;
-                updatedAt: number;
-            } | null, Name>;
-            listForAgent: FunctionReference<"query", "internal", {
-                agentId: string;
-                orgId: string;
-            }, Array<{
-                _creationTime: number;
-                _id: string;
-                agentId: string;
-                createdAt: number;
-                cronExpression: string;
-                cronJobId?: string;
-                enabled: boolean;
-                lastRunAt?: number;
-                name: string;
-                orgId: string;
-                prompt: string;
-                updatedAt: number;
-            }>, Name>;
-            listRuns: FunctionReference<"query", "internal", {
-                habitId: string;
-                orgId: string;
-            }, Array<{
-                _creationTime: number;
-                _id: string;
-                agentId: string;
-                habitId: string;
-                orgId: string;
-                ranAt: number;
-            }>, Name>;
-            updateSchedule: FunctionReference<"mutation", "internal", {
-                cronExpression?: string;
-                habitId: string;
-                name?: string;
-                orgId: string;
-                prompt?: string;
-            }, null, Name>;
-        };
         mandates: {
             get: FunctionReference<"query", "internal", {
                 agentId: string;
@@ -280,6 +286,68 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 scope: string;
             }, number, Name>;
         };
+        queue: {
+            claimNextForDelivery: FunctionReference<"mutation", "internal", {
+                orgId: string;
+                queueNamePrefix: string;
+            }, {
+                attempt: number;
+                createdAt: number;
+                deliverAt: number;
+                idempotencyKey?: string;
+                messageId: string;
+                payloadJson: string;
+                queueName: string;
+                status: "pending" | "claimed" | "delivered" | "failed";
+                updatedAt: number;
+            } | null, Name>;
+            enqueue: FunctionReference<"mutation", "internal", {
+                delaySeconds?: number;
+                idempotencyKey?: string;
+                orgId: string;
+                payloadJson: string;
+                queueName: string;
+            }, {
+                messageId: string;
+            }, Name>;
+            getMessage: FunctionReference<"query", "internal", {
+                messageId: string;
+                orgId: string;
+            }, {
+                attempt: number;
+                createdAt: number;
+                deliverAt: number;
+                idempotencyKey?: string;
+                messageId: string;
+                payloadJson: string;
+                queueName: string;
+                status: "pending" | "claimed" | "delivered" | "failed";
+                updatedAt: number;
+            } | null, Name>;
+            listPending: FunctionReference<"query", "internal", {
+                orgId: string;
+                queueNamePrefix: string;
+            }, Array<{
+                attempt: number;
+                createdAt: number;
+                deliverAt: number;
+                idempotencyKey?: string;
+                messageId: string;
+                payloadJson: string;
+                queueName: string;
+                status: "pending" | "claimed" | "delivered" | "failed";
+                updatedAt: number;
+            }>, Name>;
+            markDelivered: FunctionReference<"mutation", "internal", {
+                messageId: string;
+                orgId: string;
+            }, null, Name>;
+            markFailedForRetry: FunctionReference<"mutation", "internal", {
+                delaySeconds: number;
+                messageId: string;
+                orgId: string;
+            }, null, Name>;
+        };
         resolvers: {
             resolveManifest: FunctionReference<"query", "internal", {
                 orgId: string;
@@ -330,6 +398,17 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 workflowId: string;
             }, string, Name>;
         };
+        sandboxConfigProvider: {
+            getBoxId: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+            }, string | null, Name>;
+            setBoxId: FunctionReference<"mutation", "internal", {
+                agentId: string;
+                boxId: string;
+                orgId: string;
+            }, null, Name>;
+        };
         sessions: {
             appendReasoning: FunctionReference<"mutation", "internal", {
                 chunk: string;
@@ -346,6 +425,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 orgId: string;
                 sessionId: string;
             }, null, Name>;
+            end: FunctionReference<"mutation", "internal", {
+                orgId: string;
+                outcome: "completed" | "cancelled";
+                sessionId: string;
+            }, null, Name>;
             listEvents: FunctionReference<"query", "internal", {
                 orgId: string;
                 sessionId: string;
@@ -380,6 +464,55 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 workflowId: string;
             }, Name>;
         };
+        streams: {
+            closeStream: FunctionReference<"mutation", "internal", {
+                name: string;
+                orgId: string;
+                runId: string;
+            }, null, Name>;
+            getStreamInfo: FunctionReference<"query", "internal", {
+                name: string;
+                orgId: string;
+                runId: string;
+            }, {
+                done: boolean;
+                tailIndex: number;
+            }, Name>;
+            listChunksFromIndex: FunctionReference<"query", "internal", {
+                limit: number;
+                name: string;
+                orgId: string;
+                runId: string;
+                startIndex: number;
+            }, Array<{
+                dataBase64: string;
+                index: number;
+            }>, Name>;
+            listChunksPage: FunctionReference<"query", "internal", {
+                cursor: string | null;
+                limit: number;
+                name: string;
+                orgId: string;
+                runId: string;
+            }, {
+                continueCursor: string;
+                isDone: boolean;
+                page: Array<{
+                    dataBase64: string;
+                    index: number;
+                }>;
+            }, Name>;
+            listStreamNames: FunctionReference<"query", "internal", {
+                orgId: string;
+                runId: string;
+            }, Array<string>, Name>;
+            writeChunk: FunctionReference<"mutation", "internal", {
+                dataBase64: string;
+                name: string;
+                orgId: string;
+                runId: string;
+            }, null, Name>;
+        };
         toolApprovals: {
             respond: FunctionReference<"mutation", "internal", {
                 decision: "approved" | "denied";
@@ -432,8 +565,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         };
         wakeup: {
             cancel: FunctionReference<"mutation", "internal", {
+                messageId: string;
                 orgId: string;
-                wakeableWorkId: string;
             }, null, Name>;
             enqueue: FunctionReference<"action", "internal", {
                 agentId: string;
@@ -447,12 +580,175 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 workflowId: string;
             }, string, Name>;
             getStatus: FunctionReference<"query", "internal", {
+                messageId: string;
                 orgId: string;
-                wakeableWorkId: string;
             }, {
-                resultSummary?: string;
-                status: "pending" | "completed" | "failed" | "cancelled";
+                status: "pending" | "delivered" | "failed";
+            }, Name>;
+        };
+        world: {
+            appendEvent: FunctionReference<"mutation", "internal", {
+                correlationId?: string;
+                dataJson: string;
+                eventType: string;
+                hookId?: string;
+                orgId: string;
+                runId: string | null;
+                stepId?: string;
+            }, {
+                event: {
+                    correlationId?: string;
+                    createdAt: number;
+                    dataJson: string;
+                    eventId: string;
+                    eventType: string;
+                    hookId?: string;
+                    runId: string;
+                    seq: number;
+                    stepId?: string;
+                };
+                hook: {
+                    createdAt: number;
+                    hookId: string;
+                    runId: string;
+                    status: "pending" | "disposed";
+                    token: string;
+                    updatedAt: number;
+                } | null;
+                run: {
+                    createdAt: number;
+                    eventCount: number;
+                    runId: string;
+                    status: "running" | "completed" | "failed" | "cancelled";
+                    updatedAt: number;
+                } | null;
+                step: {
+                    createdAt: number;
+                    dataJson?: string;
+                    runId: string;
+                    status: "running" | "completed" | "failed";
+                    stepId: string;
+                    updatedAt: number;
+                } | null;
             }, Name>;
+            getEvent: FunctionReference<"query", "internal", {
+                eventId: string;
+                orgId: string;
+                runId: string;
+            }, {
+                correlationId?: string;
+                createdAt: number;
+                dataJson: string;
+                eventId: string;
+                eventType: string;
+                hookId?: string;
+                runId: string;
+                seq: number;
+                stepId?: string;
+            } | null, Name>;
+            getHook: FunctionReference<"query", "internal", {
+                hookId: string;
+                orgId: string;
+            }, {
+                createdAt: number;
+                hookId: string;
+                runId: string;
+                status: "pending" | "disposed";
+                token: string;
+                updatedAt: number;
+            } | null, Name>;
+            getHookByToken: FunctionReference<"query", "internal", {
+                orgId: string;
+                token: string;
+            }, {
+                createdAt: number;
+                hookId: string;
+                runId: string;
+                status: "pending" | "disposed";
+                token: string;
+                updatedAt: number;
+            } | null, Name>;
+            getRun: FunctionReference<"query", "internal", {
+                orgId: string;
+                runId: string;
+            }, {
+                createdAt: number;
+                eventCount: number;
+                runId: string;
+                status: "running" | "completed" | "failed" | "cancelled";
+                updatedAt: number;
+            } | null, Name>;
+            getStep: FunctionReference<"query", "internal", {
+                orgId: string;
+                runId: string;
+                stepId: string;
+            }, {
+                createdAt: number;
+                dataJson?: string;
+                runId: string;
+                status: "running" | "completed" | "failed";
+                stepId: string;
+                updatedAt: number;
+            } | null, Name>;
+            listEvents: FunctionReference<"query", "internal", {
+                orgId: string;
+                runId: string;
+            }, Array<{
+                correlationId?: string;
+                createdAt: number;
+                dataJson: string;
+                eventId: string;
+                eventType: string;
+                hookId?: string;
+                runId: string;
+                seq: number;
+                stepId?: string;
+            }>, Name>;
+            listEventsByCorrelationId: FunctionReference<"query", "internal", {
+                correlationId: string;
+                orgId: string;
+            }, Array<{
+                correlationId?: string;
+                createdAt: number;
+                dataJson: string;
+                eventId: string;
+                eventType: string;
+                hookId?: string;
+                runId: string;
+                seq: number;
+                stepId?: string;
+            }>, Name>;
+            listHooks: FunctionReference<"query", "internal", {
+                orgId: string;
+                runId: string;
+            }, Array<{
+                createdAt: number;
+                hookId: string;
+                runId: string;
+                status: "pending" | "disposed";
+                token: string;
+                updatedAt: number;
+            }>, Name>;
+            listRuns: FunctionReference<"query", "internal", {
+                orgId: string;
+            }, Array<{
+                createdAt: number;
+                eventCount: number;
+                runId: string;
+                status: "running" | "completed" | "failed" | "cancelled";
+                updatedAt: number;
+            }>, Name>;
+            listSteps: FunctionReference<"query", "internal", {
+                orgId: string;
+                runId: string;
+            }, Array<{
+                createdAt: number;
+                dataJson?: string;
+                runId: string;
+                status: "running" | "completed" | "failed";
+                stepId: string;
+                updatedAt: number;
+            }>, Name>;
         };
     };
     testFixtures: {

package/dist/component/_generated/component.js

@@ -1,10 +1 @@
-/* eslint-disable */
-/**
- * Generated `ComponentApi` utility.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
 export {};