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

package/dist/component/schema.js

@@ -8,8 +8,8 @@ import { v } from "convex/values";
 // root, which only backs THIS repo's own dev/test deployment.
 //
 // SCOPE (T2-QUATER: durableJob only. T2-QUINQUIES, this pass: WIDENS the
-// boundary to the SESSIONS surface Hestia's EveVantage V4 conversation
-// thread needs — session start/turn, streamed reasoning/tool-call events,
+// boundary to the SESSIONS surface a downstream conversation-thread
+// consumer needs — session start/turn, streamed reasoning/tool-call events,
 // toolApprovals response, replay on reconnect, dynamic resolver — see
 // README "What's callable"). Still DELIBERATELY NARROW: `skills`,
 // `connections`, `subagents`, `habits`, `sandboxConfig`, `modelKeys`,
@@ -20,10 +20,8 @@ import { v } from "convex/values";
 // can read (component isolation: this package cannot read a consumer app's
 // OWN `agents` table across the component boundary).
 export default defineSchema({
-    // durableJobs — GENERIC durable step-batch primitive (I1, SYNTHESE.md
-    // §5/§7). See convex/engine/durableJob.ts (repo root) for the full
-    // contract description; this table definition is byte-identical to the
-    // one there.
+    // durableJobs — GENERIC durable step-batch primitive. See
+    // engine/durableJob.ts for the full contract description.
     durableJobs: defineTable({
         orgId: v.string(),
         kind: v.string(),
@@ -69,9 +67,9 @@ export default defineSchema({
         instructions: v.string(),
         model: v.string(),
         reasoningEffort: v.optional(v.union(v.literal("none"), v.literal("low"), v.literal("medium"), v.literal("high"))), // eve: agent-definition.ts:315-319
-        modelProvider: v.optional(v.union(v.literal("gateway"), v.literal("openrouter"))), // notre ligne (BYOK, mvp §2.3); optional here to stay additive/backwards-compatible with rows created before this field existed
-        maxSubagents: v.optional(v.number()), // eve: agent-definition.ts:163-179, défaut 100
-        maxInputTokensPerSession: v.optional(v.union(v.number(), v.literal(false))), // eve: :195, false = illimité
+        modelProvider: v.optional(v.union(v.literal("gateway"), v.literal("openrouter"))), // intentional divergence from Eve (bring-your-own-key); optional so it stays additive/backwards-compatible with rows created before this field existed
+        maxSubagents: v.optional(v.number()), // eve: agent-definition.ts:163-179, default 100
+        maxInputTokensPerSession: v.optional(v.union(v.number(), v.literal(false))), // eve: :195, false = unlimited
         status: v.union(v.literal("draft"), v.literal("live"), v.literal("archived")),
         createdBy: v.string(),
         createdAt: v.number(),
@@ -95,21 +93,12 @@ export default defineSchema({
         .index("by_org", ["orgId"])
         .index("by_org_agent", ["orgId", "agentId"])
         .index("by_org_agent_tool", ["orgId", "agentId", "toolName"]),
-    // sessions — one conversation container per `sessions.start` call. This
-    // pass deliberately does NOT tie a session to a `@convex-dev/workflow`
-    // run (unlike the repo-root, app-level `convex/engine/sessions.ts`
-    // prototype this was ported from) — long-task durability is already
-    // covered by `engine/durableJob.ts`; a consumer that needs a durable
-    // workflow driving turns can wire one on top using `durableJob.start`
-    // with its own step function. This is a deliberate divergence ("notre
-    // ligne") from the app-level prototype, narrowing the shipped surface to
-    // what has a working component-level test harness behind it.
-    // C1.5 ("notre ligne", measured trou fixed): sessions ARE now piloted by
-    // a versioned `@convex-dev/workflow` run (component/engine/workflows.ts:
-    // sessionWorkflowV1) -- the divergence note above (T2-QUINQUIES,
-    // "deliberately does NOT tie a session to a workflow run") is retired.
-    // `workflowId`/`workflowVersion` are optional so pre-C1.5 rows (written
-    // before this migration) remain valid without a backfill.
+    // sessions — one conversation container per `sessions.start` call.
+    // "intentional divergence from Eve": a session is piloted by a VERSIONED
+    // `@convex-dev/workflow` run (engine/workflows.ts: sessionWorkflowV1), so
+    // a turn survives a deploy. `workflowId`/`workflowVersion` are optional:
+    // rows written before that workflow existed stay valid without a backfill,
+    // and a consumer driving turns itself may leave them unset.
     sessions: defineTable({
         orgId: v.string(),
         agentId: v.id("agents"),
@@ -135,16 +124,16 @@ export default defineSchema({
         orgId: v.string(),
         sessionId: v.id("sessions"),
         name: v.union(v.literal("session.started"), v.literal("turn.started"), v.literal("turn.reasoning"), v.literal("turn.toolCall.requested"), v.literal("turn.toolCall.completed"), 
-        // "notre ligne" (VP k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2):
+        // "intentional divergence from Eve" (VP k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2):
         // explicit terminal state for a one-turn approval REFUSAL, distinct
         // from "turn.toolCall.completed" (tool actually ran). Without this,
         // a denied tool call had no event of its own -- a consumer had no
         // way to tell "refused this turn" from "skipped, turn completed
-        // anyway", which is the wrong default Hestia had to code around.
+        // anyway", which is the wrong default a consumer had to code around.
         v.literal("turn.toolCall.denied"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved"), 
-        // C2 — blank event auto-inserted by `engine/awaitEventTimeout.fire`
+        // Blank event auto-inserted by `engine/awaitEventTimeout.fire`
         // (workflow#177: Convex provides no native timeout for
-        // `step.awaitEvent`). See component/engine/awaitEventTimeout.ts.
+        // `step.awaitEvent`). See engine/awaitEventTimeout.ts.
         v.literal("sandbox.timeout")),
         payload: v.optional(v.string()), // JSON-serialized, free contract per event name
         createdAt: v.number(),
@@ -152,10 +141,8 @@ export default defineSchema({
         .index("by_org", ["orgId"])
         .index("by_org_session", ["orgId", "sessionId"]),
     // ---------------------------------------------------------------------
-    // C2 — WAKE-UP WITHOUT POLLING (I2, SYNTHESE.md §5). Ported from
-    // convex/schema.ts (repo-root prototype); table shapes are byte-identical
-    // to their app-level source. See component/engine/wakeup.ts and
-    // component/engine/awaitEventTimeout.ts for the mechanism itself.
+    // WAKE-UP WITHOUT POLLING. See engine/wakeup.ts and
+    // engine/awaitEventTimeout.ts for the mechanism itself.
     // ---------------------------------------------------------------------
     // wakeableWork — GENERIC wake-up primitive. `enqueue` puts caller-supplied
     // work (an action, referenced by an opaque function-handle string) into a
@@ -210,14 +197,11 @@ export default defineSchema({
         observedResultSummary: v.optional(v.string()),
     }).index("by_org", ["orgId"]),
     // ---------------------------------------------------------------------
-    // C3 — MANDATES: "notre ligne" (autorité bornée, SYNTHESE §2/§4.e-ter).
-    // Ported from convex/schema.ts (repo-root prototype, lines 168-214);
-    // table shapes are byte-identical to their app-level source. See
-    // component/engine/mandates.ts and component/engine/wakeup.ts (the C3
-    // seam: `enqueue` now funds through `mandates.spendInternal` before any
-    // work can enter the wakeup pool).
+    // MANDATES — "intentional divergence from Eve": bounded authority. See
+    // engine/mandates.ts and engine/wakeup.ts, where `enqueue` funds through
+    // `mandates.spendInternal` before any work can enter the wakeup pool.
     // ---------------------------------------------------------------------
-    // mandates — a plafond is a DATA row scoped by orgId + agentId + scope,
+    // mandates — a cap is a DATA row scoped by orgId + agentId + scope,
     // never a constant read from code. `kind`/`rate`/`period`/`capacity` are
     // the inline contract of @convex-dev/rate-limiter ("dynamic config"): the
     // COST (`count`) is a WEIGHTED count (tokens/euros/calls), never a plain
@@ -254,12 +238,10 @@ export default defineSchema({
         .index("by_org_agent", ["orgId", "agentId"])
         .index("by_org_status", ["orgId", "status"]),
     // ---------------------------------------------------------------------
-    // C4 — HABITS: "notre ligne" (une habitude = un cron DYNAMIQUE par
-    // agent/org, SYNTHESE §2/§4.e-ter: "ce qui transforme un chat en
-    // employé"). Ported from convex/schema.ts (repo-root prototype, lines
-    // 108-124 / 210-217); table shapes are byte-identical to their app-level
-    // source. See component/engine/habits.ts (the C4 seam: `crons` is a new
-    // sub-component of THIS component, registered in component/convex.config.ts).
+    // HABITS — "intentional divergence from Eve": a habit is a DYNAMIC cron
+    // per agent/org, which is what turns a chat into an employee. See
+    // engine/habits.ts; `crons` is a sub-component of THIS component,
+    // registered in component/convex.config.ts.
     // ---------------------------------------------------------------------
     // habits — a schedule is a DATA row scoped by orgId + agentId, never a
     // constant read from a deployed `convex/crons.ts`. `cronExpression` is
@@ -297,16 +279,12 @@ export default defineSchema({
         .index("by_org", ["orgId"])
         .index("by_org_habit", ["orgId", "habitId"]),
     // ---------------------------------------------------------------------
-    // C5 — SANDBOX BRIDGE (I5, SYNTHESE.md §4.c-d: "le pont pause/réveil vers
-    // le bac à sable ET vers la délégation entre agents, même mécanisme").
-    // Ported from convex/schema.ts (repo-root prototype, sandboxRuns /
-    // sandboxCallbackDeliveries / sandboxCallbackDeadLetters); table shapes
-    // are byte-identical to their app-level source. See
-    // component/engine/sandboxCallback.ts.
+    // SANDBOX BRIDGE — the same pause/wake mechanism serves both the sandbox
+    // and agent-to-agent delegation. See engine/sandboxCallback.ts.
     //
-    // NOTRE LIGNE (frontière, C5 recherche-d'abord): the "use node" action
-    // that actually talks to `@vercel/sandbox` (convex/engine/
-    // sandboxBridgeActions.ts) CANNOT be ported into this component — the
+    // BOUNDARY, and why it is where it is: the "use node" action
+    // that actually talks to `@vercel/sandbox` CANNOT live inside this
+    // component — the
     // Convex CLI's own component bundler HARD-CRASHES on any "use node" file
     // found in a child component directory ("use node directive is not
     // supported in components", node_modules/convex/dist/cjs/cli/lib/
@@ -367,15 +345,12 @@ export default defineSchema({
         createdAt: v.number(),
     }).index("by_org", ["orgId"]),
     // ---------------------------------------------------------------------
-    // C6 — DELEGATION + VP CONNECTION (I6, SYNTHESE.md §4.d: "un agent qui
-    // délègue à un autre agent = LE MÊME système pause/réveil que le pont
-    // sandbox -- un seul système à écrire, pas deux"). Ported from
-    // convex/schema.ts (repo-root prototype, lines 74-91 / 377-467); table
-    // shapes are byte-identical to their app-level source. See
-    // component/engine/delegation.ts and component/engine/vpConnection.ts
-    // (the C6 seam: both terminate delegation/clone paths in exactly one call
-    // to THIS component's own `engine/wakeup.enqueue`, C2/C3's public action,
-    // never a second onComplete/sendEvent path).
+    // DELEGATION — an agent delegating to another agent uses THE SAME
+    // pause/wake system as the sandbox bridge: one system to maintain, not
+    // two. See engine/delegation.ts and engine/vpConnection.ts: every
+    // delegation/clone path terminates in exactly one call to this
+    // component's own public `engine/wakeup.enqueue`, never in a second
+    // onComplete/sendEvent path.
     // ---------------------------------------------------------------------
     // subagents — declared subagents, RECURSIVE (the child is a full
     // `agents` row with its own aggregate). Isolation is by construction
@@ -395,7 +370,7 @@ export default defineSchema({
         .index("by_org", ["orgId"])
         .index("by_org_parent", ["orgId", "parentAgentId"])
         .index("by_org_child", ["orgId", "childAgentId"])
-        // I6 build-time collision guard (engine/delegation.declareSubagent):
+        // Build-time collision guard (engine/delegation.declareSubagent):
         // exact-match lookup of an existing (parent, toolName) pair, no filter().
         .index("by_org_parent_tool", ["orgId", "parentAgentId", "toolName"]),
     // delegationRuns — one row per A->B delegation through a declared
@@ -421,7 +396,7 @@ export default defineSchema({
         .index("by_org_parent", ["orgId", "parentAgentId"])
         .index("by_org_workflow", ["orgId", "workflowId"])
         .index("by_org_awaitedEvent", ["orgId", "awaitedEventName"]),
-    // agentCloneRuns — I6 built-in `agent` tool (eve.dev/docs/subagents: "the
+    // agentCloneRuns — the built-in `agent` tool (eve.dev/docs/subagents: "the
     // built-in `agent` tool clones the ROOT, root-only, NOT recursive -- it
     // cannot call itself"). `viaAgentTool` is the recursion guard: a clone
     // invocation started BY a clone invocation (viaAgentTool: true passed in)
@@ -441,9 +416,9 @@ export default defineSchema({
     })
         .index("by_org", ["orgId"])
         .index("by_org_agent", ["orgId", "agentId"]),
-    // vpConnections — I6 (mvp-evevantage.md §2.2 "Travail d'équipe"). The
+    // vpConnections — teamwork. The
     // four VantagePeers tools (memory, tasks, messages, notes) wired as a
-    // CONNECTION of the agent aggregate, notre ligne. 0..1 row per agent;
+    // CONNECTION of the agent aggregate, an intentional divergence from Eve. 0..1 row per agent;
     // absence means "use the defaults" (all four ON) -- see
     // `engine/vpConnection.ts:defaultToggles`. DIRECT access: invocation
     // goes through a caller-supplied Convex function handle

package/dist/component/testFixtures/callerSteps.js

@@ -56,7 +56,7 @@ export const alwaysSucceeds = internalMutation({
         return null;
     },
 });
-// Fails on every attempt -- used to prove "abandon after N échecs". Attempt
+// Fails on every attempt -- used to prove abandonment after N failures. Attempt
 // count is observable via `getAttemptCount` even though every DB write this
 // function might otherwise make would be rolled back by the throw.
 export const alwaysFails = internalMutation({

package/dist/component/testFixtures/delegationDemoWorkflow.js

@@ -4,14 +4,13 @@ import { components, internal } from "../_generated/api.js";
 import { internalMutation, mutation } from "../_generated/server.js";
 import { requireOrgId } from "../lib/auth.js";
 // testFixtures/delegationDemoWorkflow — TEST-ONLY reference PARENT-side
-// recipient for delegation (C6), ported from
-// convex/engine/delegationDemoWorkflow.ts. This is exactly the "bespoke
+// recipient for delegation. This is exactly the "bespoke
 // workflow" shape `engine/wakeup.ts`'s own comment describes ("any
 // workflow -- a session, a durable job, or a bespoke one -- can be the wake
 // target"): it parks on `step.awaitEvent` and, once
 // `engine.wakeup.onWorkComplete` fires `sendEvent` (via
 // `engine.delegation.delegateToSubagent` -> `engine.wakeup.enqueue`, the
-// SAME public action C2/C3 ships), it patches the SAME `delegationRuns`
+// same public action this component ships), it patches the SAME `delegationRuns`
 // row `delegateToSubagent` created -- proving A paused and was woken by
 // B's completion, with zero polling.
 export const workflow = new WorkflowManager(components.workflow);

package/dist/component/testFixtures/sandboxDemoWorkflow.js

@@ -4,8 +4,8 @@ import { components, internal } from "../_generated/api.js";
 import { internalMutation, mutation } from "../_generated/server.js";
 import { requireOrgId } from "../lib/auth.js";
 // testFixtures/sandboxDemoWorkflow — TEST-ONLY reference recipient for the
-// C5 sandbox bridge, ported from convex/engine/sandboxDemoWorkflow.ts, same
-// shape/role as testFixtures/wakeupDemoWorkflow.ts (C2). A real consumer's
+// sandbox bridge, same shape/role as testFixtures/wakeupDemoWorkflow.ts.
+// A real consumer's
 // own workflow parks on `step.awaitEvent({ name: <awaitedEventName passed
 // to engine/sandboxCallback.startRun> })` and does nothing else. Proves
 // (component/sandboxCallback.componentPackaging.test.ts) the ONLY way this

package/dist/component/testFixtures/wakeupDemoWorkflow.js

@@ -4,7 +4,7 @@ import { components, internal } from "../_generated/api.js";
 import { internalMutation, mutation } from "../_generated/server.js";
 import { requireOrgId } from "../lib/auth.js";
 // testFixtures/wakeupDemoWorkflow — TEST-ONLY reference recipient for the
-// wake-up mechanism (C2), ported from convex/engine/wakeupDemoWorkflow.ts.
+// wake-up mechanism.
 // A real consumer's own workflow does exactly this shape: call
 // `step.awaitEvent({ name: <same name passed to engine/wakeup.enqueue> })`
 // and do nothing else until it resolves. Proves (and is exercised by the
@@ -14,7 +14,7 @@ import { requireOrgId } from "../lib/auth.js";
 // this file. Also exercises `engine/awaitEventTimeout` by accepting the
 // blank `sandbox.timeout` event name as an alternate wake source.
 //
-// Versioned workflow discipline (workflow#35, I0 §7.1): ship
+// Versioned workflow discipline (workflow#35): ship
 // `...V2` rather than editing `wakeupDemoWorkflowV1` in place once
 // referenced by live work (not a live concern for a test fixture, kept for
 // parity with the app-level source it was ported from).

package/package.json

@@ -1,16 +1,26 @@
 {
   "name": "@vantageos/agent-engine",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "description": "Reusable Convex component: durable agent engine. Agent = data aggregate (root sheet + child tables), never compiled code. Built on @convex-dev/workflow + @convex-dev/workpool (+ @convex-dev/agent). Eve parity by design.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "FSL-1.1-Apache-2.0",
+  "keywords": [
+    "convex",
+    "convex-component",
+    "agents",
+    "durable-agents",
+    "ai-agents",
+    "workflow",
+    "vantageos"
+  ],
   "publishConfig": {
     "access": "public",
     "tag": "alpha"
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "exports": {
     "./package.json": "./package.json",
@@ -32,9 +42,10 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run build && npm run check:public",
     "check:generated": "node scripts/check-generated-freshness.mjs",
-    "check:generated:content": "node scripts/check-generated-content.mjs"
+    "check:generated:content": "node scripts/check-generated-content.mjs",
+    "check:public": "node scripts/check-public-package.mjs"
   },
   "dependencies": {
     "@convex-dev/agent": "0.6.4",