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

package/dist/component/engine/connections.js

@@ -0,0 +1,254 @@
+import { WorkflowManager } from "@convex-dev/workflow";
+import { v } from "convex/values";
+import { components } from "../_generated/api.js";
+import { mutation, query } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
+import { encryptSecret } from "../lib/connectionSecret.js";
+const workflow = new WorkflowManager(components.workflow);
+const authModeValidator = v.union(v.literal("app-token"), v.literal("user-oauth"), v.literal("none"), v.literal("header"));
+function principalTypeForAuthMode(authMode) {
+    return authMode === "user-oauth" ? "user" : "app";
+}
+const connectionTypeValidator = v.union(v.literal("mcp"), v.literal("openapi"));
+const connectionStatusValidator = v.union(v.literal("active"), v.literal("pending_authorization"), v.literal("error"));
+const connectionPublicDoc = v.object({
+    _id: v.id("connections"),
+    _creationTime: v.number(),
+    orgId: v.string(),
+    agentId: v.id("agents"),
+    type: connectionTypeValidator,
+    name: v.string(),
+    serverConfig: v.string(),
+    authMode: authModeValidator,
+    principalType: v.union(v.literal("app"), v.literal("user")),
+    status: connectionStatusValidator,
+    hasSecret: v.boolean(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+function toPublicDoc(row) {
+    return {
+        _id: row._id,
+        _creationTime: row._creationTime,
+        orgId: row.orgId,
+        agentId: row.agentId,
+        type: row.type,
+        name: row.name,
+        serverConfig: row.serverConfig,
+        authMode: row.authMode,
+        principalType: principalTypeForAuthMode(row.authMode),
+        status: row.status,
+        hasSecret: row.encryptedSecretCiphertext !== undefined,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+    };
+}
+export const create = mutation({
+    args: {
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        type: connectionTypeValidator,
+        name: v.string(),
+        serverConfig: v.string(),
+        authMode: authModeValidator,
+        secretPlaintext: v.optional(v.string()),
+        encryptionKeyBase64: v.optional(v.string()),
+    },
+    returns: v.id("connections"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const agent = await ctx.db.get(args.agentId);
+        assertSameOrg(orgId, agent, "Agent not found");
+        if (args.name.trim().length === 0) {
+            throw new Error("Validation: name must not be empty");
+        }
+        let encryptedSecretCiphertext;
+        let encryptedSecretIv;
+        if (args.authMode === "app-token" || args.authMode === "header") {
+            if (!args.secretPlaintext) {
+                throw new Error(`MUST_REFUSE: connection authMode "${args.authMode}" requires secretPlaintext, none was supplied`);
+            }
+            if (!args.encryptionKeyBase64) {
+                throw new Error(`MUST_REFUSE: connection authMode "${args.authMode}" requires encryptionKeyBase64, none was supplied`);
+            }
+            const encrypted = await encryptSecret(args.secretPlaintext, args.encryptionKeyBase64);
+            encryptedSecretCiphertext = encrypted.ciphertextBase64;
+            encryptedSecretIv = encrypted.ivBase64;
+        }
+        else if (args.authMode === "none") {
+            if (args.secretPlaintext) {
+                throw new Error('MUST_REFUSE: connection authMode "none" must not carry a secretPlaintext');
+            }
+        }
+        const now = Date.now();
+        return await ctx.db.insert("connections", {
+            orgId,
+            agentId: args.agentId,
+            type: args.type,
+            name: args.name,
+            serverConfig: args.serverConfig,
+            authMode: args.authMode,
+            encryptedSecretCiphertext,
+            encryptedSecretIv,
+            status: "active",
+            createdAt: now,
+            updatedAt: now,
+        });
+    },
+});
+export const get = query({
+    args: { orgId: v.string(), connectionId: v.id("connections") },
+    returns: connectionPublicDoc,
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const row = await ctx.db.get(args.connectionId);
+        assertSameOrg(orgId, row, "Connection not found");
+        return toPublicDoc(row);
+    },
+});
+export const listByAgent = query({
+    args: { orgId: v.string(), agentId: v.id("agents") },
+    returns: v.array(connectionPublicDoc),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const agent = await ctx.db.get(args.agentId);
+        assertSameOrg(orgId, agent, "Agent not found");
+        const rows = await ctx.db
+            .query("connections")
+            .withIndex("by_org_agent", (q) => q.eq("orgId", orgId).eq("agentId", args.agentId))
+            .collect();
+        return rows.map((row) => toPublicDoc(row));
+    },
+});
+export const requestAuthorization = mutation({
+    args: {
+        orgId: v.string(),
+        connectionId: v.id("connections"),
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+        url: v.string(),
+        userCode: v.string(),
+    },
+    returns: v.id("connectionAuthorizations"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const connection = await ctx.db.get(args.connectionId);
+        assertSameOrg(orgId, connection, "Connection not found");
+        if (connection.authMode !== "user-oauth") {
+            throw new Error(`MUST_REFUSE: requestAuthorization requires authMode "user-oauth", connection has "${connection.authMode}"`);
+        }
+        if (args.workflowId.length === 0) {
+            throw new Error("MUST_REFUSE: workflowId must not be empty");
+        }
+        if (args.awaitedEventName.length === 0) {
+            throw new Error("MUST_REFUSE: awaitedEventName must not be empty");
+        }
+        if (args.url.trim().length === 0) {
+            throw new Error("MUST_REFUSE: authorization.required challenge requires a non-empty url, none was supplied");
+        }
+        if (args.userCode.trim().length === 0) {
+            throw new Error("MUST_REFUSE: authorization.required challenge requires a non-empty userCode, none was supplied");
+        }
+        const now = Date.now();
+        const authorizationId = await ctx.db.insert("connectionAuthorizations", {
+            orgId,
+            connectionId: args.connectionId,
+            workflowId: args.workflowId,
+            awaitedEventName: args.awaitedEventName,
+            url: args.url,
+            userCode: args.userCode,
+            status: "pending",
+            createdAt: now,
+            updatedAt: now,
+        });
+        await ctx.db.patch(args.connectionId, {
+            status: "pending_authorization",
+            updatedAt: now,
+        });
+        return authorizationId;
+    },
+});
+export const getAuthorizationStatus = query({
+    args: { orgId: v.string(), connectionAuthorizationId: v.id("connectionAuthorizations") },
+    returns: v.object({
+        status: v.union(v.literal("pending"), v.literal("authorized"), v.literal("denied")),
+        url: v.string(),
+        userCode: v.string(),
+        resultSummary: v.optional(v.string()),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const row = await ctx.db.get(args.connectionAuthorizationId);
+        assertSameOrg(orgId, row, "Connection authorization not found");
+        return {
+            status: row.status,
+            url: row.url,
+            userCode: row.userCode,
+            resultSummary: row.resultSummary,
+        };
+    },
+});
+export const completeAuthorization = mutation({
+    args: {
+        orgId: v.string(),
+        connectionAuthorizationId: v.id("connectionAuthorizations"),
+        outcome: v.union(v.literal("authorized"), v.literal("denied")),
+        secretPlaintext: v.optional(v.string()),
+        encryptionKeyBase64: v.optional(v.string()),
+        resultSummary: v.optional(v.string()),
+    },
+    returns: v.object({
+        outcome: v.union(v.literal("woke"), v.literal("already-resolved")),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const authorization = await ctx.db.get(args.connectionAuthorizationId);
+        assertSameOrg(orgId, authorization, "Connection authorization not found");
+        if (authorization.status !== "pending") {
+            return { outcome: "already-resolved" };
+        }
+        const connection = await ctx.db.get(authorization.connectionId);
+        assertSameOrg(orgId, connection, "Connection not found");
+        let encryptedSecretCiphertext = connection.encryptedSecretCiphertext;
+        let encryptedSecretIv = connection.encryptedSecretIv;
+        let connectionStatus = "error";
+        if (args.outcome === "authorized") {
+            if (!args.secretPlaintext) {
+                throw new Error('MUST_REFUSE: completeAuthorization outcome "authorized" requires secretPlaintext, none was supplied');
+            }
+            if (!args.encryptionKeyBase64) {
+                throw new Error('MUST_REFUSE: completeAuthorization outcome "authorized" requires encryptionKeyBase64, none was supplied');
+            }
+            const encrypted = await encryptSecret(args.secretPlaintext, args.encryptionKeyBase64);
+            encryptedSecretCiphertext = encrypted.ciphertextBase64;
+            encryptedSecretIv = encrypted.ivBase64;
+            connectionStatus = "active";
+        }
+        const now = Date.now();
+        await ctx.db.patch(authorization._id, {
+            status: args.outcome,
+            resultSummary: args.resultSummary,
+            updatedAt: now,
+            resolvedAt: now,
+        });
+        await ctx.db.patch(connection._id, {
+            encryptedSecretCiphertext,
+            encryptedSecretIv,
+            status: connectionStatus,
+            updatedAt: now,
+        });
+        await workflow.sendEvent(ctx, {
+            workflowId: authorization.workflowId,
+            name: authorization.awaitedEventName,
+            validator: v.object({
+                status: v.union(v.literal("completed"), v.literal("failed")),
+                resultSummary: v.optional(v.string()),
+            }),
+            value: {
+                status: args.outcome === "authorized" ? "completed" : "failed",
+                resultSummary: args.resultSummary,
+            },
+        });
+        return { outcome: "woke" };
+    },
+});

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

@@ -17,9 +17,9 @@ export declare const listSubagents: import("convex/server").RegisteredQuery<"pub
     orgId: string;
     createdAt: number;
     toolName: string;
-    enabled: boolean;
     parentAgentId: import("convex/values").GenericId<"agents">;
     childAgentId: import("convex/values").GenericId<"agents">;
+    enabled: boolean;
 }[]>>;
 export declare const delegateToSubagent: import("convex/server").RegisteredAction<"public", {
     payload?: string | undefined;

package/dist/component/engine/delegation.js

@@ -2,46 +2,7 @@ import { v } from "convex/values";
 import { api, internal } from "../_generated/api.js";
 import { action, internalMutation, internalQuery, mutation, query, } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/delegation — an agent delegating to another agent uses THE SAME
-// pause/wake system (awaitEvent/sendEvent) as the sandbox bridge: one
-// system to maintain, not two. Every delegation path below (declared
-// subagent AND the built-in `agent` clone tool) terminates in exactly ONE
-// call to `engine.wakeup.enqueue` -- the same public action this component
-// already ships, imported here and never reimplemented.
-// grep proof: this file makes zero calls to `wakeupPool.*` / `workflow.*`
-// directly; the only wake-capable call in this module is
-// `api.engine.wakeup.enqueue` at the bottom of `delegateToSubagent` and
-// `invokeAgentClone`.
-//
-// orgId discipline (component/lib/auth.ts): every PUBLIC function takes
-// `orgId` as an explicit ARGUMENT (auth does not propagate across a
-// component boundary), same as engine/mandates.ts / engine/wakeup.ts.
-// `delegateToSubagent`/`invokeAgentClone` are `action`s because they each
-// call `api.engine.wakeup.enqueue` (itself an action: the two-transaction
-// funding protocol) -- `orgId` is threaded explicitly through
-// every hop, never relying on any identity propagation across the boundary.
-// Reserved tool name for the built-in, root-only, non-recursive clone tool
-// (eve.dev/docs/subagents). A declared subagent may never claim this name --
-// that would silently shadow the built-in, which eve explicitly refuses to
-// do ("eve rejects the build rather than picking a winner").
 export const BUILTIN_AGENT_TOOL_NAME = "agent";
-// ---------------------------------------------------------------------
-// (a.1) DECLARED SUBAGENTS -- strict isolation, build-time collision guard
-// ---------------------------------------------------------------------
-// declareSubagent — registers a declared subagent as a NAMED tool on the
-// parent. Isolation is by construction: this mutation writes ONLY the
-// parent->child link + toolName; it never copies a single field out of the
-// child's own `skills`/`connections`/`toolApprovals` rows onto the parent,
-// and never will -- a declared subagent's own aggregate is the ONLY place
-// its slots ever live (eve.dev/docs/subagents, verbatim: "a declared
-// subagent inherits nothing from the root's authored slots").
-//
-// BUILD-TIME COLLISION GUARD: `toolName` must be unique among (1) the
-// reserved built-in `agent` tool name, (2) every OTHER declared subagent of
-// this same parent, and (3) every `toolApprovals` row already registered
-// for this parent (a toolApprovals row is how this engine represents "a
-// named tool this agent already exposes"). Any collision REJECTS the
-// mutation -- the row is never written, there is no silent "last one wins".
 export const declareSubagent = mutation({
     args: {
         orgId: v.string(),
@@ -119,18 +80,6 @@ export const listSubagents = query({
             .collect();
     },
 });
-// ---------------------------------------------------------------------
-// (a.2) DELEGATION -- reuses `engine.wakeup.enqueue` end to end
-// ---------------------------------------------------------------------
-// delegateToSubagent — A delegates to a declared subagent B by the SAME
-// pause/wake mechanism the sandbox bridge uses: it enqueues the
-// caller-supplied `workFunctionHandle` (an action that performs B's turn)
-// through `api.engine.wakeup.enqueue`. That enqueue funds through
-// `mandates.spendInternal` (the funding choke point, untouched), puts the work
-// into `wakeupPool`, and when it resolves, `engine.wakeup.onWorkComplete`
-// calls `workflow.sendEvent` (workflowId, awaitedEventName, ...) -- waking
-// whatever workflow step A's own session parked on `step.awaitEvent`. There
-// is no second onComplete/sendEvent path anywhere in this file.
 export const delegateToSubagent = action({
     args: {
         orgId: v.string(),
@@ -164,10 +113,6 @@ export const delegateToSubagent = action({
             workflowId: args.workflowId,
             awaitedEventName: args.awaitedEventName,
         });
-        // THE reuse point: no bespoke pause/wake code below this line -- this
-        // is a direct call into this component's own PUBLIC `engine.wakeup.enqueue`
-        // action. `orgId` is threaded explicitly (no identity propagation
-        // across the component boundary).
         await ctx.runAction(api.engine.wakeup.enqueue, {
             orgId,
             agentId: subagent.childAgentId,
@@ -182,19 +127,6 @@ export const delegateToSubagent = action({
         return delegationRunId;
     },
 });
-// ---------------------------------------------------------------------
-// (a.3) BUILT-IN `agent` TOOL -- root-only clone, NOT recursive
-// ---------------------------------------------------------------------
-// invokeAgentClone — the built-in `agent` tool (eve.dev/docs/subagents): a
-// clone of the ROOT agent, invocable by the root itself, but the clone
-// CANNOT call itself again. `viaAgentTool` is the recursion guard: the
-// root's own first call always passes `viaAgentTool: false` (or omits it).
-// Anything invoking this action must set `viaAgentTool: true` on any call
-// made FROM INSIDE a clone's own work -- and that is exactly the value this
-// handler refuses. There is no code path in this engine that can reach the
-// pool a second time for the same clone chain: the guard runs BEFORE
-// `wakeup.enqueue` is ever called, so a recursive attempt never enters the
-// workpool at all.
 export const invokeAgentClone = action({
     args: {
         orgId: v.string(),
@@ -229,8 +161,6 @@ export const invokeAgentClone = action({
             workflowId: args.workflowId,
             awaitedEventName: args.awaitedEventName,
         });
-        // Same reuse point as `delegateToSubagent`: one call into the SAME
-        // public `engine.wakeup.enqueue`, nothing bespoke.
         await ctx.runAction(api.engine.wakeup.enqueue, {
             orgId,
             agentId: args.agentId,
@@ -245,10 +175,6 @@ export const invokeAgentClone = action({
         return cloneRunId;
     },
 });
-// ---------------------------------------------------------------------
-// INTERNAL helpers -- unreachable from any client, same discipline as
-// `engine/wakeup.enqueueInternal`.
-// ---------------------------------------------------------------------
 export const getSubagentInternal = internalQuery({
     args: { orgId: v.string(), subagentId: v.id("subagents") },
     returns: v.union(v.object({

package/dist/component/engine/directory.js

@@ -1,24 +1,6 @@
 import { v } from "convex/values";
 import { query } from "../_generated/server.js";
 import { requireOrgId } from "../lib/auth.js";
-// engine/directory — component-boundary port of the app-level
-// `convex/directory.ts:listByOrg`.
-//
-// Trust-boundary divergence from the app-level prototype (see
-// component/lib/auth.ts): auth does NOT propagate across a component
-// boundary, so `orgId` is a caller-supplied ARGUMENT here (deny by default
-// via `requireOrgId(args.orgId)`), never read from `ctx.auth`. The consumer
-// app has already authenticated its user and resolved orgId on its own
-// side before calling in.
-//
-// Shape divergence: the app-level prototype also reports
-// `subagentCount`/`connectionCount` by joining the `subagents` and
-// `connections` tables. Those tables are NOT (yet) re-hosted inside this
-// component boundary (see component/schema.ts SCOPE note) -- porting a
-// join against tables this component does not own would violate component
-// isolation. `listByOrg` here therefore returns only what this component's
-// own `agents` table can answer; counts can be added once `subagents`/
-// `connections` gain their own component-level test harness.
 export const listByOrg = query({
     args: { orgId: v.string() },
     returns: v.array(v.object({

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

@@ -1,4 +1,5 @@
 import { WorkflowManager, type WorkflowId } from "@convex-dev/workflow";
+type JobRunStatus = "running" | "completed" | "abandoned" | "cancelled";
 export declare const workflow: WorkflowManager;
 export declare const start: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
@@ -6,12 +7,12 @@ export declare const start: import("convex/server").RegisteredMutation<"public",
     totalSteps: number;
     maxAttemptsPerStep: number;
     kind: string;
-}, Promise<import("convex/values").GenericId<"durableJobs">>>;
+}, Promise<string>>;
 export declare const getStatus: import("convex/server").RegisteredQuery<"public", {
     orgId: string;
-    jobId: import("convex/values").GenericId<"durableJobs">;
+    jobId: string;
 }, Promise<{
-    status: "running" | "completed" | "abandoned" | "cancelled";
+    status: JobRunStatus;
     cursor: number;
     totalSteps: number;
     lastError: string | undefined;
@@ -19,7 +20,7 @@ export declare const getStatus: import("convex/server").RegisteredQuery<"public"
 }>>;
 export declare const cancel: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
-    jobId: import("convex/values").GenericId<"durableJobs">;
+    jobId: string;
 }, Promise<null>>;
 export declare const getJobInternal: import("convex/server").RegisteredQuery<"internal", {
     jobId: import("convex/values").GenericId<"durableJobs">;
@@ -44,3 +45,32 @@ export declare const markCompletedInternal: import("convex/server").RegisteredMu
 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;
+}, Promise<{
+    cursor: number;
+    totalSteps: number;
+    maxAttemptsPerStep: number;
+    status: JobRunStatus;
+} | null>>;
+export declare const runStepInternalV2: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    stepIndex: number;
+    runId: string;
+}, Promise<null>>;
+export declare const markAbandonedInternalV2: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    stepIndex: number;
+    runId: string;
+    error: string;
+}, Promise<null>>;
+export declare const markCompletedInternalV2: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    runId: string;
+}, Promise<null>>;
+export declare const durableJobWorkflowV2: import("convex/server").RegisteredMutation<"internal", import("@convex-dev/workflow").WorkflowArgs<{
+    orgId: import("convex/values").VString<string, "required">;
+    runId: import("convex/values").VString<string, "required">;
+}>, WorkflowId>;
+export {};