@vantageos/agent-engine 0.1.0-alpha.5 → 0.1.0-alpha.7

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

@@ -0,0 +1,75 @@
+import type { Id } from "../_generated/dataModel.js";
+export declare const BUILTIN_AGENT_TOOL_NAME = "agent";
+export declare const declareSubagent: import("convex/server").RegisteredMutation<"public", {
+    description?: string | undefined;
+    orgId: string;
+    toolName: string;
+    parentAgentId: import("convex/values").GenericId<"agents">;
+    childAgentId: import("convex/values").GenericId<"agents">;
+}, Promise<import("convex/values").GenericId<"subagents">>>;
+export declare const listSubagents: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    parentAgentId: import("convex/values").GenericId<"agents">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"subagents">;
+    _creationTime: number;
+    description?: string | undefined;
+    orgId: string;
+    createdAt: number;
+    toolName: string;
+    enabled: boolean;
+    parentAgentId: import("convex/values").GenericId<"agents">;
+    childAgentId: import("convex/values").GenericId<"agents">;
+}[]>>;
+export declare const delegateToSubagent: import("convex/server").RegisteredAction<"public", {
+    payload?: string | undefined;
+    orgId: string;
+    workflowId: string;
+    awaitedEventName: string;
+    scope: string;
+    reason: string;
+    cost: number;
+    subagentId: import("convex/values").GenericId<"subagents">;
+    workFunctionHandle: string;
+}, Promise<Id<"delegationRuns">>>;
+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;
+    cost: number;
+    workFunctionHandle: string;
+    viaAgentTool: boolean;
+}, Promise<Id<"agentCloneRuns">>>;
+export declare const getSubagentInternal: import("convex/server").RegisteredQuery<"internal", {
+    orgId: string;
+    subagentId: import("convex/values").GenericId<"subagents">;
+}, Promise<{
+    parentAgentId: import("convex/values").GenericId<"agents">;
+    childAgentId: import("convex/values").GenericId<"agents">;
+    toolName: string;
+    enabled: boolean;
+} | null>>;
+export declare const getAgentInternal: import("convex/server").RegisteredQuery<"internal", {
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"agents">;
+} | null>>;
+export declare const recordDelegationStartInternal: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    workflowId: string;
+    toolName: 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">;
+    awaitedEventName: string;
+}, Promise<import("convex/values").GenericId<"agentCloneRuns">>>;

package/dist/component/engine/delegation.js

@@ -0,0 +1,327 @@
+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(),
+        parentAgentId: v.id("agents"),
+        childAgentId: v.id("agents"),
+        toolName: v.string(),
+        description: v.optional(v.string()),
+    },
+    returns: v.id("subagents"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const parent = await ctx.db.get(args.parentAgentId);
+        assertSameOrg(orgId, parent, "Parent agent not found");
+        const child = await ctx.db.get(args.childAgentId);
+        assertSameOrg(orgId, child, "Child agent not found");
+        const toolName = args.toolName.trim();
+        if (toolName.length === 0) {
+            throw new Error("Validation: toolName must not be empty");
+        }
+        if (args.parentAgentId === args.childAgentId) {
+            throw new Error("Build rejected: an agent cannot be declared as its own subagent");
+        }
+        if (toolName === BUILTIN_AGENT_TOOL_NAME) {
+            throw new Error(`Build rejected: tool name "${toolName}" collides with the built-in ` +
+                `"agent" clone tool -- eve rejects the build rather than picking a winner`);
+        }
+        const collidingSubagent = await ctx.db
+            .query("subagents")
+            .withIndex("by_org_parent_tool", (q) => q.eq("orgId", orgId).eq("parentAgentId", args.parentAgentId).eq("toolName", toolName))
+            .first();
+        if (collidingSubagent) {
+            throw new Error(`Build rejected: tool name "${toolName}" already claimed by another ` +
+                `declared subagent of this agent -- eve rejects the build rather ` +
+                `than picking a winner`);
+        }
+        const collidingTool = await ctx.db
+            .query("toolApprovals")
+            .withIndex("by_org_agent_tool", (q) => q.eq("orgId", orgId).eq("agentId", args.parentAgentId).eq("toolName", toolName))
+            .first();
+        if (collidingTool) {
+            throw new Error(`Build rejected: tool name "${toolName}" collides with an existing ` +
+                `tool already registered on this agent -- eve rejects the build ` +
+                `rather than picking a winner`);
+        }
+        const now = Date.now();
+        return await ctx.db.insert("subagents", {
+            orgId,
+            parentAgentId: args.parentAgentId,
+            childAgentId: args.childAgentId,
+            toolName,
+            description: args.description,
+            enabled: true,
+            createdAt: now,
+        });
+    },
+});
+export const listSubagents = query({
+    args: { orgId: v.string(), parentAgentId: v.id("agents") },
+    returns: v.array(v.object({
+        _id: v.id("subagents"),
+        _creationTime: v.number(),
+        orgId: v.string(),
+        parentAgentId: v.id("agents"),
+        childAgentId: v.id("agents"),
+        toolName: v.string(),
+        description: v.optional(v.string()),
+        enabled: v.boolean(),
+        createdAt: v.number(),
+    })),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        return await ctx.db
+            .query("subagents")
+            .withIndex("by_org_parent", (q) => q.eq("orgId", orgId).eq("parentAgentId", args.parentAgentId))
+            .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(),
+        subagentId: v.id("subagents"),
+        scope: v.string(),
+        cost: v.number(),
+        reason: v.string(),
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+        workFunctionHandle: v.string(),
+        payload: v.optional(v.string()),
+    },
+    returns: v.id("delegationRuns"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const subagent = await ctx.runQuery(internal.engine.delegation.getSubagentInternal, {
+            orgId,
+            subagentId: args.subagentId,
+        });
+        if (!subagent) {
+            throw new Error("Subagent not found");
+        }
+        if (!subagent.enabled) {
+            throw new Error(`Subagent "${subagent.toolName}" is disabled`);
+        }
+        const delegationRunId = await ctx.runMutation(internal.engine.delegation.recordDelegationStartInternal, {
+            orgId,
+            parentAgentId: subagent.parentAgentId,
+            childAgentId: subagent.childAgentId,
+            toolName: subagent.toolName,
+            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,
+            scope: args.scope,
+            cost: args.cost,
+            reason: args.reason,
+            workflowId: args.workflowId,
+            awaitedEventName: args.awaitedEventName,
+            workFunctionHandle: args.workFunctionHandle,
+            payload: args.payload,
+        });
+        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(),
+        agentId: v.id("agents"),
+        scope: v.string(),
+        cost: v.number(),
+        reason: v.string(),
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+        workFunctionHandle: v.string(),
+        payload: v.optional(v.string()),
+        viaAgentTool: v.boolean(),
+    },
+    returns: v.id("agentCloneRuns"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        if (args.viaAgentTool) {
+            throw new Error("Build rejected: the built-in \"agent\" clone tool is root-only and " +
+                "NOT recursive -- a clone invocation cannot invoke the agent tool " +
+                "again");
+        }
+        const agent = await ctx.runQuery(internal.engine.delegation.getAgentInternal, {
+            orgId,
+            agentId: args.agentId,
+        });
+        if (!agent) {
+            throw new Error("Agent not found");
+        }
+        const cloneRunId = await ctx.runMutation(internal.engine.delegation.recordCloneStartInternal, {
+            orgId,
+            agentId: args.agentId,
+            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,
+            scope: args.scope,
+            cost: args.cost,
+            reason: args.reason,
+            workflowId: args.workflowId,
+            awaitedEventName: args.awaitedEventName,
+            workFunctionHandle: args.workFunctionHandle,
+            payload: args.payload,
+        });
+        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({
+        parentAgentId: v.id("agents"),
+        childAgentId: v.id("agents"),
+        toolName: v.string(),
+        enabled: v.boolean(),
+    }), v.null()),
+    handler: async (ctx, args) => {
+        const row = await ctx.db.get(args.subagentId);
+        if (!row || row.orgId !== args.orgId)
+            return null;
+        return {
+            parentAgentId: row.parentAgentId,
+            childAgentId: row.childAgentId,
+            toolName: row.toolName,
+            enabled: row.enabled,
+        };
+    },
+});
+export const getAgentInternal = internalQuery({
+    args: { orgId: v.string(), agentId: v.id("agents") },
+    returns: v.union(v.object({ _id: v.id("agents") }), v.null()),
+    handler: async (ctx, args) => {
+        const row = await ctx.db.get(args.agentId);
+        if (!row || row.orgId !== args.orgId)
+            return null;
+        return { _id: row._id };
+    },
+});
+export const recordDelegationStartInternal = internalMutation({
+    args: {
+        orgId: v.string(),
+        parentAgentId: v.id("agents"),
+        childAgentId: v.id("agents"),
+        toolName: v.string(),
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+    },
+    returns: v.id("delegationRuns"),
+    handler: async (ctx, args) => {
+        const now = Date.now();
+        return await ctx.db.insert("delegationRuns", {
+            orgId: args.orgId,
+            parentAgentId: args.parentAgentId,
+            childAgentId: args.childAgentId,
+            toolName: args.toolName,
+            workflowId: args.workflowId,
+            awaitedEventName: args.awaitedEventName,
+            status: "pending",
+            createdAt: now,
+            updatedAt: now,
+        });
+    },
+});
+export const recordCloneStartInternal = internalMutation({
+    args: {
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+    },
+    returns: v.id("agentCloneRuns"),
+    handler: async (ctx, args) => {
+        const now = Date.now();
+        return await ctx.db.insert("agentCloneRuns", {
+            orgId: args.orgId,
+            agentId: args.agentId,
+            workflowId: args.workflowId,
+            awaitedEventName: args.awaitedEventName,
+            status: "pending",
+            createdAt: now,
+            updatedAt: now,
+        });
+    },
+});

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

@@ -0,0 +1,9 @@
+export declare const listByOrg: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"agents">;
+    name: string;
+    status: "draft" | "live" | "archived";
+    model: string;
+    createdAt: number;
+}[]>>;

package/dist/component/engine/directory.js

@@ -0,0 +1,45 @@
+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({
+        _id: v.id("agents"),
+        name: v.string(),
+        status: v.union(v.literal("draft"), v.literal("live"), v.literal("archived")),
+        model: v.string(),
+        createdAt: v.number(),
+    })),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const agents = await ctx.db
+            .query("agents")
+            .withIndex("by_org", (q) => q.eq("orgId", orgId))
+            .collect();
+        return agents.map((agent) => ({
+            _id: agent._id,
+            name: agent.name,
+            status: agent.status,
+            model: agent.model,
+            createdAt: agent.createdAt,
+        }));
+    },
+});

package/dist/component/engine/durableJob.js

@@ -3,9 +3,9 @@ import { WorkflowManager } from "@convex-dev/workflow";
 import { components, internal } from "../_generated/api.js";
 import { internalMutation, internalQuery, mutation, query, } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// durableJobs — THE SURVIVAL CONTRACT (I1, SYNTHESE.md §5/§7): "mise en
-// pause à la frontière d'étape, rejeu déterministe, reprise, abandon après
-// N échecs." This ENVELOPS `@convex-dev/workflow` -- it does not reimplement
+// durableJobs — THE SURVIVAL CONTRACT: pause at the step boundary,
+// deterministic replay, resume, and abandon after N failures. This ENVELOPS
+// `@convex-dev/workflow` -- it does not reimplement
 // durable execution. Every real unit of work (the caller-supplied
 // `stepFunctionHandle`) runs inside its own bounded mutation call; the
 // workflow persists `cursor` (steps [0, cursor) done) between calls, so a
@@ -13,8 +13,8 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // still completes -- no single call has to survive past the ceiling, only
 // the aggregate progress does.
 //
-// Contract surface (this is what a consumer -- VantagePeers/Sigma first --
-// calls; see examples/vantage-peers-long-task for a worked integration):
+// Contract surface (this is what a consumer calls; see
+// examples/vantage-peers-long-task for a worked integration):
 //   1. `start`      -- enqueue a job of N steps, driven by a step function
 //                       the CALLER owns (created via `createFunctionHandle`
 //                       in the caller's own app). We never read the
@@ -40,7 +40,7 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 //         which the workflow handler catches and turns into
 //         `status: "abandoned"` with `abandonedAtStep` + `lastError`.
 //
-// Versioned workflow discipline (workflow#35, I0 §7.1) -- same as
+// Versioned workflow discipline (workflow#35) -- same as
 // `engine/workflows.ts:sessionWorkflowV1`: never edit `durableJobWorkflowV1`
 // in place once jobs reference it; ship `...V2` and drain v1 first.
 const CURRENT_WORKFLOW_VERSION = "v1";

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

@@ -0,0 +1,70 @@
+export declare const create: import("convex/server").RegisteredMutation<"public", {
+    name: string;
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+    cronExpression: string;
+    prompt: string;
+}, Promise<import("convex/values").GenericId<"habits">>>;
+export declare const get: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    habitId: import("convex/values").GenericId<"habits">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"habits">;
+    _creationTime: number;
+    cronJobId?: string | undefined;
+    lastRunAt?: number | undefined;
+    name: string;
+    orgId: string;
+    createdAt: number;
+    updatedAt: number;
+    agentId: import("convex/values").GenericId<"agents">;
+    cronExpression: string;
+    prompt: string;
+    enabled: boolean;
+} | null>>;
+export declare const listForAgent: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"habits">;
+    _creationTime: number;
+    cronJobId?: string | undefined;
+    lastRunAt?: number | undefined;
+    name: string;
+    orgId: string;
+    createdAt: number;
+    updatedAt: number;
+    agentId: import("convex/values").GenericId<"agents">;
+    cronExpression: string;
+    prompt: string;
+    enabled: boolean;
+}[]>>;
+export declare const updateSchedule: import("convex/server").RegisteredMutation<"public", {
+    name?: string | undefined;
+    cronExpression?: string | undefined;
+    prompt?: string | undefined;
+    orgId: string;
+    habitId: import("convex/values").GenericId<"habits">;
+}, Promise<null>>;
+export declare const disable: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    habitId: import("convex/values").GenericId<"habits">;
+}, Promise<null>>;
+export declare const enable: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    habitId: import("convex/values").GenericId<"habits">;
+}, Promise<null>>;
+export declare const run: import("convex/server").RegisteredMutation<"internal", {
+    habitId: import("convex/values").GenericId<"habits">;
+}, Promise<null>>;
+export declare const listRuns: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    habitId: import("convex/values").GenericId<"habits">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"habitRuns">;
+    _creationTime: number;
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+    habitId: import("convex/values").GenericId<"habits">;
+    ranAt: number;
+}[]>>;