@vantageos/agent-engine 0.1.0-alpha.7 → 0.3.0-alpha.0

package/README.md

@@ -1,10 +1,12 @@
 # @vantageos/agent-engine
 
-A reusable [Convex component](https://www.convex.dev/components) that provides
-a durable **agent engine**: sessions, delegation, tool approvals, scheduled
-"habits", bounded spending "mandates", and long-task survival — all built on
-top of [`@convex-dev/workflow`](https://www.npmjs.com/package/@convex-dev/workflow)
-and [`@convex-dev/workpool`](https://www.npmjs.com/package/@convex-dev/workpool).
+A reusable [Convex component](https://www.convex.dev/components) that
+provides a durable **agent engine**: sessions, delegation, tool approvals,
+scheduled "habits", bounded spending "mandates", and long-task survival —
+all built on top of
+[`@convex-dev/workflow`](https://www.npmjs.com/package/@convex-dev/workflow)
+and
+[`@convex-dev/workpool`](https://www.npmjs.com/package/@convex-dev/workpool).
 
 **An agent is a data aggregate, not compiled code.** Creating an agent means
 writing a row (plus child rows for skills, tool approvals, connections,
@@ -31,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`:
@@ -77,61 +89,143 @@ scoped by `orgId` first, deny-by-default.
 ### API surface (component/, current release)
 
 ```
-components.agentEngine.engine.agents.create({ orgId, createdBy, name, description?, instructions, model, reasoningEffort?, modelProvider?, maxSubagents?, maxInputTokensPerSession? }) -> Id<"agents">
+components.agentEngine.engine.agents.create({
+  orgId, createdBy, name, description?, instructions, model,
+  reasoningEffort?, modelProvider?, maxSubagents?,
+  maxInputTokensPerSession?,
+}) -> Id<"agents">
 components.agentEngine.engine.agents.get({ orgId, agentId }) -> agent | null
 
-components.agentEngine.engine.directory.listByOrg({ orgId }) -> { _id, name, status, model, createdAt }[]
-
-components.agentEngine.engine.resolvers.resolveManifest({ orgId, sessionId }) -> { agentId, name, instructions, model, toolApprovals[] }
-
-components.agentEngine.engine.sessions.start({ orgId, agentId, createdBy }) -> { sessionId: Id<"sessions">, workflowId: string }
-components.agentEngine.engine.sessions.sendTurn({ orgId, sessionId, input }) -> null
-components.agentEngine.engine.sessions.appendReasoning({ orgId, sessionId, chunk }) -> null
-components.agentEngine.engine.sessions.requestToolCall({ orgId, sessionId, toolName, argsJson }) -> { authorized, approvalPending, denied }
-components.agentEngine.engine.sessions.completeToolCall({ orgId, sessionId, toolName, resultJson }) -> null
-components.agentEngine.engine.sessions.completeTurn({ orgId, sessionId }) -> null
-components.agentEngine.engine.sessions.listEvents({ orgId, sessionId }) -> sessionEvent[]
-
-components.agentEngine.engine.toolApprovals.respond({ orgId, sessionId, toolName, decision: "approved"|"denied", updatePolicy?: "always"|"once"|"never" }) -> null
-
-components.agentEngine.engine.wakeup.enqueue({ orgId, agentId, mandateScope, cost, reason, workFunctionHandle, workflowId, awaitedEventName }) -> Id<"wakeableWork">  (action)
-components.agentEngine.engine.wakeup.cancel({ orgId, wakeableWorkId }) -> null
-components.agentEngine.engine.wakeup.getStatus({ orgId, wakeableWorkId }) -> { status, resultSummary?, ... }
-
-components.agentEngine.engine.durableJob.start({ orgId, kind, stepFunctionHandle, totalSteps, maxAttemptsPerStep }) -> Id<"durableJobs">
-components.agentEngine.engine.durableJob.getStatus({ orgId, jobId }) -> { status, cursor, totalSteps, lastError?, abandonedAtStep? }
+components.agentEngine.engine.directory.listByOrg({ orgId })
+  -> { _id, name, status, model, createdAt }[]
+
+components.agentEngine.engine.resolvers.resolveManifest({
+  orgId, sessionId,
+}) -> { agentId, name, instructions, model, toolApprovals[] }
+
+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,
+// cross-org or non-session id is refused as "Session not found".
+components.agentEngine.engine.sessions.sendTurn({
+  orgId, sessionId, input,
+}) -> null
+components.agentEngine.engine.sessions.appendReasoning({
+  orgId, sessionId, chunk,
+}) -> null
+components.agentEngine.engine.sessions.requestToolCall({
+  orgId, sessionId, toolName, argsJson,
+}) -> { authorized, approvalPending, denied }
+components.agentEngine.engine.sessions.completeToolCall({
+  orgId, sessionId, toolName, resultJson,
+}) -> null
+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,
+}) -> { _id /* journal eventId */, _creationTime /* event createdAt, ms */,
+        name, payload?, createdAt }[]   (read from the world journal)
+
+components.agentEngine.engine.toolApprovals.respond({
+  orgId, sessionId, toolName,
+  decision: "approved"|"denied",
+  updatePolicy?: "always"|"once"|"never",
+}) -> null
+
+components.agentEngine.engine.wakeup.enqueue({
+  orgId, agentId, mandateScope, cost, reason,
+  workFunctionHandle, workflowId, awaitedEventName,
+}) -> string  (action; the world-queue messageId)
+components.agentEngine.engine.wakeup.cancel({ orgId, messageId }) -> null
+components.agentEngine.engine.wakeup.getStatus({
+  orgId, messageId,
+}) -> { status: "pending" | "delivered" | "failed" }
+
+components.agentEngine.engine.durableJob.start({
+  orgId, kind, stepFunctionHandle, totalSteps, maxAttemptsPerStep,
+}) -> 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
 
-components.agentEngine.engine.mandates.set({ orgId, agentId, scope, kind, rate, period, capacity? }) -> Id<"mandates">
-components.agentEngine.engine.mandates.get({ orgId, agentId, scope }) -> mandate | null
-components.agentEngine.engine.mandates.spend({ orgId, agentId, scope, cost, reason }) -> { ok, approvalId? }
-components.agentEngine.engine.mandates.listApprovals({ orgId, agentId }) -> approvalRequest[]
-components.agentEngine.engine.mandates.resolveApproval({ orgId, approvalId, resolvedBy, status: "approved"|"denied" }) -> null
-components.agentEngine.engine.mandates.usageCount({ orgId, agentId, scope }) -> number
-
-components.agentEngine.engine.habits.create({ orgId, agentId, name, cronExpression, prompt }) -> Id<"habits">
+components.agentEngine.engine.mandates.set({
+  orgId, agentId, scope, kind, rate, period, capacity?,
+}) -> Id<"mandates">
+components.agentEngine.engine.mandates.get({
+  orgId, agentId, scope,
+}) -> mandate | null
+components.agentEngine.engine.mandates.spend({
+  orgId, agentId, scope, cost, reason,
+}) -> { ok, approvalId? }
+components.agentEngine.engine.mandates.listApprovals({
+  orgId, agentId,
+}) -> approvalRequest[]
+components.agentEngine.engine.mandates.resolveApproval({
+  orgId, approvalId, resolvedBy, status: "approved"|"denied",
+}) -> null
+components.agentEngine.engine.mandates.usageCount({
+  orgId, agentId, scope,
+}) -> number
+
+components.agentEngine.engine.habits.create({
+  orgId, agentId, name, cronExpression, prompt,
+}) -> Id<"habits">
 components.agentEngine.engine.habits.get({ orgId, habitId }) -> habit | null
 components.agentEngine.engine.habits.listForAgent({ orgId, agentId }) -> habit[]
-components.agentEngine.engine.habits.updateSchedule({ orgId, habitId, cronExpression }) -> null
+components.agentEngine.engine.habits.updateSchedule({
+  orgId, habitId, cronExpression,
+}) -> null
 components.agentEngine.engine.habits.disable({ orgId, habitId }) -> null
 components.agentEngine.engine.habits.enable({ orgId, habitId }) -> null
 components.agentEngine.engine.habits.listRuns({ orgId, habitId }) -> habitRun[]
 
-components.agentEngine.engine.sandboxCallback.startRun({ orgId, workflowId, awaitedEventName, timeoutMs }) -> Id<"sandboxRuns">
-components.agentEngine.engine.sandboxCallback.attachSandboxId({ orgId, sandboxRunId, sandboxId }) -> null
-components.agentEngine.engine.sandboxCallback.getStatus({ orgId, sandboxRunId }) -> { status, resultSummary?, ... }
-components.agentEngine.engine.sandboxCallback.processCallback({ orgId, sandboxRunId, deliveryId, status, resultSummary? }) -> { outcome: "woke"|"duplicate" }
-components.agentEngine.engine.sandboxCallback.deadLetterMalformed({ orgId?, deliveryId, reason, rawBody }) -> null
-
-components.agentEngine.engine.delegation.declareSubagent({ orgId, parentAgentId, childAgentId, toolName, description? }) -> Id<"subagents">
-components.agentEngine.engine.delegation.listSubagents({ orgId, parentAgentId }) -> subagent[]
-components.agentEngine.engine.delegation.delegateToSubagent({ orgId, subagentId, ... }) -> null   (action)
-components.agentEngine.engine.delegation.invokeAgentClone({ orgId, agentId, ... }) -> null   (action; root-only, non-recursive by construction)
-
-components.agentEngine.engine.vpConnection.get({ orgId, agentId }) -> vpConnection | null
-components.agentEngine.engine.vpConnection.getToggles({ orgId, agentId }) -> { memoryEnabled, tasksEnabled, messagesEnabled, notesEnabled }
-components.agentEngine.engine.vpConnection.setToggles({ orgId, agentId, memoryEnabled?, tasksEnabled?, messagesEnabled?, notesEnabled? }) -> Id<"vpConnections">
-components.agentEngine.engine.vpConnection.invokeVpTool({ orgId, agentId, tool, vpFunctionHandle, argsJson }) -> null   (action)
+components.agentEngine.engine.sandboxCallback.startRun({
+  orgId, workflowId, awaitedEventName, timeoutMs,
+}) -> Id<"sandboxRuns">
+components.agentEngine.engine.sandboxCallback.attachSandboxId({
+  orgId, sandboxRunId, sandboxId,
+}) -> null
+components.agentEngine.engine.sandboxCallback.getStatus({
+  orgId, sandboxRunId,
+}) -> { status, resultSummary?, ... }
+components.agentEngine.engine.sandboxCallback.processCallback({
+  orgId, sandboxRunId, deliveryId, status, resultSummary?,
+}) -> { outcome: "woke"|"duplicate" }
+components.agentEngine.engine.sandboxCallback.deadLetterMalformed({
+  orgId?, deliveryId, reason, rawBody,
+}) -> null
+
+components.agentEngine.engine.delegation.declareSubagent({
+  orgId, parentAgentId, childAgentId, toolName, description?,
+}) -> Id<"subagents">
+components.agentEngine.engine.delegation.listSubagents({
+  orgId, parentAgentId,
+}) -> subagent[]
+components.agentEngine.engine.delegation.delegateToSubagent({
+  orgId, subagentId, ...,
+}) -> null   (action)
+components.agentEngine.engine.delegation.invokeAgentClone({
+  orgId, agentId, ...,
+}) -> null   (action; root-only, non-recursive by construction)
+
+components.agentEngine.engine.vpConnection.get({
+  orgId, agentId,
+}) -> vpConnection | null
+components.agentEngine.engine.vpConnection.getToggles({
+  orgId, agentId,
+}) -> { memoryEnabled, tasksEnabled, messagesEnabled, notesEnabled }
+components.agentEngine.engine.vpConnection.setToggles({
+  orgId, agentId, memoryEnabled?, tasksEnabled?,
+  messagesEnabled?, notesEnabled?,
+}) -> Id<"vpConnections">
+components.agentEngine.engine.vpConnection.invokeVpTool({
+  orgId, agentId, tool, vpFunctionHandle, argsJson,
+}) -> null   (action)
 ```
 
 ### Concepts
@@ -164,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

@@ -1,28 +1,26 @@
-/**
- * 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";
 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_legacyBind from "../testFixtures/legacyBind.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,43 +29,33 @@ 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/legacyBind": typeof testFixtures_legacyBind;
     "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">;
@@ -76,6 +64,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();