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

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

@@ -23,10 +23,15 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         agents: {
             create: FunctionReference<"mutation", "internal", {
                 createdBy: string;
+                description?: string;
                 instructions: string;
+                maxInputTokensPerSession?: number | false;
+                maxSubagents?: number;
                 model: string;
+                modelProvider?: "gateway" | "openrouter";
                 name: string;
                 orgId: string;
+                reasoningEffort?: "none" | "low" | "medium" | "high";
             }, string, Name>;
             get: FunctionReference<"query", "internal", {
                 agentId: string;
@@ -36,14 +41,88 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 _id: string;
                 createdAt: number;
                 createdBy: string;
+                description?: string;
                 instructions: string;
+                maxInputTokensPerSession?: number | false;
+                maxSubagents?: number;
                 model: string;
+                modelProvider?: "gateway" | "openrouter";
                 name: string;
                 orgId: string;
+                reasoningEffort?: "none" | "low" | "medium" | "high";
                 status: "draft" | "live" | "archived";
                 updatedAt: number;
             } | null, Name>;
         };
+        awaitEventTimeout: {
+            cancel: FunctionReference<"mutation", "internal", {
+                orgId: string;
+                timeoutRowId: string;
+            }, null, Name>;
+            schedule: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+                sessionId: string;
+                timeoutMs: number;
+            }, string, Name>;
+        };
+        delegation: {
+            declareSubagent: FunctionReference<"mutation", "internal", {
+                childAgentId: string;
+                description?: string;
+                orgId: string;
+                parentAgentId: string;
+                toolName: string;
+            }, string, Name>;
+            delegateToSubagent: FunctionReference<"action", "internal", {
+                awaitedEventName: string;
+                cost: number;
+                orgId: string;
+                payload?: string;
+                reason: string;
+                scope: string;
+                subagentId: string;
+                workFunctionHandle: string;
+                workflowId: string;
+            }, string, Name>;
+            invokeAgentClone: FunctionReference<"action", "internal", {
+                agentId: string;
+                awaitedEventName: string;
+                cost: number;
+                orgId: string;
+                payload?: string;
+                reason: string;
+                scope: string;
+                viaAgentTool: boolean;
+                workFunctionHandle: string;
+                workflowId: string;
+            }, string, Name>;
+            listSubagents: FunctionReference<"query", "internal", {
+                orgId: string;
+                parentAgentId: string;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                childAgentId: string;
+                createdAt: number;
+                description?: string;
+                enabled: boolean;
+                orgId: string;
+                parentAgentId: string;
+                toolName: string;
+            }>, Name>;
+        };
+        directory: {
+            listByOrg: FunctionReference<"query", "internal", {
+                orgId: string;
+            }, Array<{
+                _id: string;
+                createdAt: number;
+                model: string;
+                name: string;
+                status: "draft" | "live" | "archived";
+            }>, Name>;
+        };
         durableJob: {
             cancel: FunctionReference<"mutation", "internal", {
                 jobId: string;
@@ -67,6 +146,140 @@ 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;
+                orgId: string;
+                scope: string;
+            }, {
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                capacity?: number;
+                createdAt: number;
+                kind: "token bucket" | "fixed window";
+                orgId: string;
+                period: number;
+                rate: number;
+                scope: string;
+                updatedAt: number;
+            } | null, Name>;
+            listApprovals: FunctionReference<"query", "internal", {
+                agentId?: string;
+                orgId: string;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                createdAt: number;
+                orgId: string;
+                reason: string;
+                requestedCost: number;
+                resolvedAt?: number;
+                resolvedBy?: string;
+                scope: string;
+                status: "pending" | "approved" | "denied";
+            }>, Name>;
+            resolveApproval: FunctionReference<"mutation", "internal", {
+                approvalId: string;
+                decision: "approved" | "denied";
+                orgId: string;
+                resolvedBy: string;
+            }, null, Name>;
+            set: FunctionReference<"mutation", "internal", {
+                agentId: string;
+                capacity?: number;
+                kind: "token bucket" | "fixed window";
+                orgId: string;
+                period: number;
+                rate: number;
+                scope: string;
+            }, string, Name>;
+            spend: FunctionReference<"mutation", "internal", {
+                agentId: string;
+                cost: number;
+                orgId: string;
+                reason: string;
+                scope: string;
+            }, {
+                approvalId?: string;
+                ok: boolean;
+            }, Name>;
+            usageCount: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+                scope: string;
+            }, number, Name>;
+        };
         resolvers: {
             resolveManifest: FunctionReference<"query", "internal", {
                 orgId: string;
@@ -82,6 +295,41 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 }>;
             }, Name>;
         };
+        sandboxCallback: {
+            attachSandboxId: FunctionReference<"mutation", "internal", {
+                orgId: string;
+                sandboxId: string;
+                sandboxRunId: string;
+            }, null, Name>;
+            deadLetterMalformed: FunctionReference<"mutation", "internal", {
+                deliveryId: string;
+                orgId?: string;
+                rawBody: string;
+                reason: string;
+            }, null, Name>;
+            getStatus: FunctionReference<"query", "internal", {
+                orgId: string;
+                sandboxRunId: string;
+            }, {
+                resultSummary?: string;
+                status: "pending" | "completed" | "failed" | "timedOut";
+            }, Name>;
+            processCallback: FunctionReference<"mutation", "internal", {
+                deliveryId: string;
+                orgId: string;
+                resultSummary?: string;
+                sandboxRunId: string;
+                status: "completed" | "failed";
+            }, {
+                outcome: "woke" | "duplicate" | "dead-lettered";
+            }, Name>;
+            startRun: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+                timeoutMs: number;
+                workflowId: string;
+            }, string, Name>;
+        };
         sessions: {
             appendReasoning: FunctionReference<"mutation", "internal", {
                 chunk: string;
@@ -105,7 +353,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 _creationTime: number;
                 _id: string;
                 createdAt: number;
-                name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.toolCall.denied" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
+                name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.toolCall.denied" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved" | "sandbox.timeout";
                 payload?: string;
             }>, Name>;
             requestToolCall: FunctionReference<"mutation", "internal", {
@@ -127,7 +375,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 agentId: string;
                 createdBy: string;
                 orgId: string;
-            }, string, Name>;
+            }, {
+                sessionId: string;
+                workflowId: string;
+            }, Name>;
         };
         toolApprovals: {
             respond: FunctionReference<"mutation", "internal", {
@@ -138,5 +389,98 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 updatePolicy?: "always" | "once" | "never";
             }, null, Name>;
         };
+        vpConnection: {
+            get: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+            }, {
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                createdAt: number;
+                memoryEnabled: boolean;
+                messagesEnabled: boolean;
+                notesEnabled: boolean;
+                orgId: string;
+                tasksEnabled: boolean;
+                updatedAt: number;
+            } | null, Name>;
+            getToggles: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+            }, {
+                memoryEnabled: boolean;
+                messagesEnabled: boolean;
+                notesEnabled: boolean;
+                tasksEnabled: boolean;
+            }, Name>;
+            invokeVpTool: FunctionReference<"action", "internal", {
+                agentId: string;
+                argsJson: string;
+                orgId: string;
+                tool: "memory" | "tasks" | "messages" | "notes";
+                vpFunctionHandle: string;
+            }, null, Name>;
+            setToggles: FunctionReference<"mutation", "internal", {
+                agentId: string;
+                memoryEnabled?: boolean;
+                messagesEnabled?: boolean;
+                notesEnabled?: boolean;
+                orgId: string;
+                tasksEnabled?: boolean;
+            }, string, Name>;
+        };
+        wakeup: {
+            cancel: FunctionReference<"mutation", "internal", {
+                orgId: string;
+                wakeableWorkId: string;
+            }, null, Name>;
+            enqueue: FunctionReference<"action", "internal", {
+                agentId: string;
+                awaitedEventName: string;
+                cost: number;
+                orgId: string;
+                payload?: string;
+                reason: string;
+                scope: string;
+                workFunctionHandle: string;
+                workflowId: string;
+            }, string, Name>;
+            getStatus: FunctionReference<"query", "internal", {
+                orgId: string;
+                wakeableWorkId: string;
+            }, {
+                resultSummary?: string;
+                status: "pending" | "completed" | "failed" | "cancelled";
+            }, Name>;
+        };
+    };
+    testFixtures: {
+        delegationDemoWorkflow: {
+            start: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+            }, {
+                workflowId: string;
+            }, Name>;
+        };
+        sandboxDemoWorkflow: {
+            start: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+            }, {
+                resultId: string;
+                workflowId: string;
+            }, Name>;
+        };
+        wakeupDemoWorkflow: {
+            start: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+            }, {
+                resultId: string;
+                workflowId: string;
+            }, Name>;
+        };
     };
 };

package/dist/component/convex.config.js

@@ -2,6 +2,9 @@ import { defineComponent } from "convex/server";
 import workflow from "@convex-dev/workflow/convex.config";
 import workpool from "@convex-dev/workpool/convex.config";
 import agent from "@convex-dev/agent/convex.config";
+import rateLimiter from "@convex-dev/rate-limiter/convex.config";
+import shardedCounter from "@convex-dev/sharded-counter/convex.config";
+import crons from "@convex-dev/crons/convex.config";
 // @vantageos/agent-engine — Convex COMPONENT definition (pattern
 // `@convex-dev/*`, verified against the published shape of
 // `@convex-dev/workflow` — `defineComponent(name)` + a `convex.config.ts`
@@ -32,9 +35,25 @@ import agent from "@convex-dev/agent/convex.config";
 // awaitEventTimeouts, wakeableWork) is deliberately NOT yet re-hosted
 // here — porting those without a working component-level test harness
 // behind each of them would violate Day 128 (never ship unverified).
+// C3 (this pass): mandates ("notre ligne", autorité bornée) are now hosted
+// under this component boundary, following the exact same trio the
+// repo-root prototype used (I0 §3, `convex/convex.config.ts`) -- official
+// `@convex-dev/*` libraries only, NO canary/alpha dependency for a
+// guardrail: `rate-limiter` for the fails-closed spend gate itself,
+// `sharded-counter` for the usage rollup. See component/engine/mandates.ts.
+// C4 (this pass): habits ("notre ligne", un cron DYNAMIQUE par agent/org)
+// are now hosted under this component boundary, ported byte-identical from
+// the repo-root prototype (convex/habits.ts). `crons` is a sub-component of
+// THIS component -- create/updateSchedule/enable/disable register or tear
+// down a runtime cron job via `@convex-dev/crons` inside the SAME Convex
+// mutation transaction that writes the `habits` row, so no habit schedule
+// change ever requires a redeploy. See component/engine/habits.ts.
 const component = defineComponent("agentEngine");
 component.use(workflow);
 component.use(workpool, { name: "agentTurnPool" });
 component.use(workpool, { name: "wakeupPool" });
 component.use(agent);
+component.use(rateLimiter);
+component.use(shardedCounter);
+component.use(crons);
 export default component;

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

@@ -1,4 +1,9 @@
 export declare const create: import("convex/server").RegisteredMutation<"public", {
+    description?: string | undefined;
+    reasoningEffort?: "none" | "low" | "medium" | "high" | undefined;
+    modelProvider?: "gateway" | "openrouter" | undefined;
+    maxSubagents?: number | undefined;
+    maxInputTokensPerSession?: number | false | undefined;
     name: string;
     orgId: string;
     instructions: string;
@@ -11,6 +16,11 @@ export declare const get: import("convex/server").RegisteredQuery<"public", {
 }, Promise<{
     _id: import("convex/values").GenericId<"agents">;
     _creationTime: number;
+    description?: string | undefined;
+    reasoningEffort?: "none" | "low" | "medium" | "high" | undefined;
+    modelProvider?: "gateway" | "openrouter" | undefined;
+    maxSubagents?: number | undefined;
+    maxInputTokensPerSession?: number | false | undefined;
     name: string;
     orgId: string;
     status: "draft" | "live" | "archived";

package/dist/component/engine/agents.js

@@ -8,13 +8,21 @@ import { requireOrgId } from "../lib/auth.js";
 // `create`/`get`, no `update`/`list`/skills/connections — the full agent
 // aggregate CRUD stays out of this component boundary for this pass (see
 // component/schema.ts SCOPE note).
+const reasoningEffort = v.union(v.literal("none"), v.literal("low"), v.literal("medium"), v.literal("high"));
+const modelProvider = v.union(v.literal("gateway"), v.literal("openrouter"));
+const maxInputTokensPerSession = v.union(v.number(), v.literal(false));
 const agentDoc = v.object({
     _id: v.id("agents"),
     _creationTime: v.number(),
     orgId: v.string(),
     name: v.string(),
+    description: v.optional(v.string()),
     instructions: v.string(),
     model: v.string(),
+    reasoningEffort: v.optional(reasoningEffort),
+    modelProvider: v.optional(modelProvider),
+    maxSubagents: v.optional(v.number()),
+    maxInputTokensPerSession: v.optional(maxInputTokensPerSession),
     status: v.union(v.literal("draft"), v.literal("live"), v.literal("archived")),
     createdBy: v.string(),
     createdAt: v.number(),
@@ -25,8 +33,13 @@ export const create = mutation({
         orgId: v.string(),
         createdBy: v.string(),
         name: v.string(),
+        description: v.optional(v.string()),
         instructions: v.string(),
         model: v.string(),
+        reasoningEffort: v.optional(reasoningEffort),
+        modelProvider: v.optional(modelProvider),
+        maxSubagents: v.optional(v.number()),
+        maxInputTokensPerSession: v.optional(maxInputTokensPerSession),
     },
     returns: v.id("agents"),
     handler: async (ctx, args) => {
@@ -43,12 +56,20 @@ export const create = mutation({
         if (args.model.trim().length === 0) {
             throw new Error("Validation: model must not be empty");
         }
+        if (args.maxSubagents !== undefined && args.maxSubagents < 0) {
+            throw new Error("Validation: maxSubagents must not be negative");
+        }
         const now = Date.now();
         return await ctx.db.insert("agents", {
             orgId,
             name: args.name,
+            description: args.description,
             instructions: args.instructions,
             model: args.model,
+            reasoningEffort: args.reasoningEffort,
+            modelProvider: args.modelProvider,
+            maxSubagents: args.maxSubagents,
+            maxInputTokensPerSession: args.maxInputTokensPerSession,
             status: "live",
             createdBy: args.createdBy,
             createdAt: now,

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

@@ -0,0 +1,13 @@
+export declare const schedule: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    sessionId: import("convex/values").GenericId<"sessions">;
+    awaitedEventName: string;
+    timeoutMs: number;
+}, Promise<import("convex/values").GenericId<"awaitEventTimeouts">>>;
+export declare const cancel: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    timeoutRowId: import("convex/values").GenericId<"awaitEventTimeouts">;
+}, Promise<null>>;
+export declare const fire: import("convex/server").RegisteredMutation<"internal", {
+    timeoutRowId: import("convex/values").GenericId<"awaitEventTimeouts">;
+}, Promise<null>>;

package/dist/component/engine/awaitEventTimeout.js

@@ -0,0 +1,82 @@
+import { v } from "convex/values";
+import { internal } from "../_generated/api.js";
+import { internalMutation, mutation } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
+// engine/awaitEventTimeout — self-built timeout for step.awaitEvent
+// (workflow#177: "Convex does not provide a native timeout for
+// awaitEvent"). PORTED from convex/engine/awaitEventTimeout.ts (repo-root
+// prototype) into the component boundary (C2). We schedule a mutation that
+// fires a "blank" `sandbox.timeout` sessionEvent at the deadline; the
+// workflow's `awaitEvent` call is written to also accept this event name so
+// it wakes up even if the awaited event never arrives. Pattern:
+// maintainer's posted code in workflow#177, adapted to our sessionEvents
+// table.
+//
+// C2 MIGRATION NOTE ("notre ligne"): orgId is an EXPLICIT ARGUMENT on
+// every public function, never derived from `ctx.auth` -- auth does NOT
+// propagate across a component boundary (component/lib/auth.ts). Also:
+// `sessionEvents.name`'s union in component/schema.ts did not previously
+// include `sandbox.timeout` -- it has been added there (and mirrored in
+// `engine/sessions.listEvents`'s return validator) as part of this
+// migration, otherwise `fire`'s insert below would not compile under the
+// strict build.
+export const schedule = mutation({
+    args: {
+        orgId: v.string(),
+        sessionId: v.id("sessions"),
+        awaitedEventName: v.string(),
+        timeoutMs: v.number(),
+    },
+    returns: v.id("awaitEventTimeouts"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        if (args.timeoutMs <= 0) {
+            throw new Error("Validation: timeoutMs must be > 0");
+        }
+        const timeoutRowId = await ctx.db.insert("awaitEventTimeouts", {
+            orgId,
+            sessionId: args.sessionId,
+            awaitedEventName: args.awaitedEventName,
+            deadlineAt: Date.now() + args.timeoutMs,
+        });
+        const scheduledFunctionId = await ctx.scheduler.runAfter(args.timeoutMs, internal.engine.awaitEventTimeout.fire, { timeoutRowId });
+        await ctx.db.patch(timeoutRowId, { scheduledFunctionId });
+        return timeoutRowId;
+    },
+});
+export const cancel = mutation({
+    args: { orgId: v.string(), timeoutRowId: v.id("awaitEventTimeouts") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const row = await ctx.db.get(args.timeoutRowId);
+        assertSameOrg(orgId, row, "Timeout not found");
+        if (!row.firedAt && !row.cancelledAt && row.scheduledFunctionId) {
+            await ctx.scheduler.cancel(row.scheduledFunctionId);
+            await ctx.db.patch(args.timeoutRowId, { cancelledAt: Date.now() });
+        }
+        return null;
+    },
+});
+// internal — invoked only by the scheduler, never by a client.
+export const fire = internalMutation({
+    args: { timeoutRowId: v.id("awaitEventTimeouts") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const row = await ctx.db.get(args.timeoutRowId);
+        if (!row || row.firedAt || row.cancelledAt) {
+            return null; // already resolved by the real event or by a prior fire
+        }
+        await ctx.db.patch(args.timeoutRowId, { firedAt: Date.now() });
+        await ctx.db.insert("sessionEvents", {
+            orgId: row.orgId,
+            sessionId: row.sessionId,
+            name: "sandbox.timeout",
+            payload: JSON.stringify({ awaitedEventName: row.awaitedEventName }),
+            createdAt: Date.now(),
+        });
+        return null;
+    },
+});