@junejs/server 1.0.0-dev.17 → 1.0.0-dev.20

package/src/agent-durable.ts

@@ -19,6 +19,7 @@ import {
   AgentSession,
   ResumeAuthorizationError,
   withSystem,
+  type ChannelPolicy,
   type EventSink,
   type TurnEvent,
   type Model,
@@ -35,6 +36,7 @@ import type { Resources } from "@junejs/core/resources";
 import {
   channelDispatch,
   DeliverUnsupportedError,
+  actionToTool,
   resolveChannel,
   type AgentDefinition,
   type Channel,
@@ -42,6 +44,7 @@ import {
   type ChannelFactory,
   type ResumeDeliveryTarget,
 } from "@junejs/core/agent-config";
+import { connectAll, type Connection } from "@junejs/core/connections";
 import { ensureScope, runInScope } from "@junejs/db";
 import { isolateLocal } from "./isolate-local";
 import { assertCoreRuntimeVersion } from "./core-version";
@@ -198,9 +201,12 @@ export type DoAgentDef = {
   model: Model;
   tools: Tool[];
   instructions?: string;
-  // Per-channel-source system overlays (see AgentDefinition.channelInstructions) — the
-  // shared agent branches by real inbound source, no userText marker.
-  channelInstructions?: Record<string, string>;
+  // Per-channel-source turn policies (see AgentDefinition.channelInstructions):
+  // an overlay string, or a ChannelPolicy carrying overlay/overlayMode/denyTools
+  // (#149 — derived from agent-level instructions.<source>.md + surfaces config
+  // by assembleDurable). The shared agent branches by real inbound source, no
+  // userText marker.
+  channelInstructions?: Record<string, string | ChannelPolicy>;
   // Channels whose CAPABILITY tools should be available to this session's turns. Their
   // tools are built HERE, in the DO isolate, from `env` — because a channel's tool `run`
   // is a closure (over the bot token, etc.) that can't cross the worker→DO RPC. This is
@@ -213,6 +219,12 @@ export type DoAgentDef = {
   // constructor cannot await, so a provider is resolved lazily at the first
   // turn (once per DO instance) with this def's `env`.
   resources?: Resources | ((env: unknown) => Promise<Resources> | Resources);
+  // Outbound connection DEFINITIONS (external MCP/OpenAPI servers). Wiring them
+  // is network I/O (connectAll), which a DO constructor cannot await — resolved
+  // lazily at the first turn, their tools merged into the agent's tool set
+  // before any session is constructed. The native equivalent happens at
+  // assembly (assembleAgent → connectAll).
+  connections?: Connection[];
   services?: unknown;
   // Called on every turn.failed for this session — the app's seam for routing turn
   // failures to its own telemetry (Sentry, a ledger, …). Providing it REPLACES the
@@ -256,13 +268,15 @@ export class AgentDurableObject {
   private readonly model: Model;
   private readonly tools: Tool[];
   private readonly channels: Channel[];
-  private readonly channelInstructions?: Record<string, string>;
+  private readonly channelInstructions?: Record<string, string | ChannelPolicy>;
   // A bag is used as-is; a provider (bindWorkerResources' shape) is resolved
   // lazily at the first turn with the def's env — opening a D1 handle is async
   // and this constructor cannot await. Resolved once, shared across turns (env
   // is stable per isolate, like bindWorkerResources memoizes per worker isolate).
   private readonly resourcesInput: DoAgentDef["resources"];
   private resourcesOpened: Promise<Resources> | undefined;
+  private readonly connectionsInput: Connection[] | undefined;
+  private connectionsOpened: Promise<void> | undefined;
   private readonly doEnv: unknown;
   private readonly services: unknown;
   private resolveResources(): Promise<Resources> {
@@ -270,11 +284,40 @@ export class AgentDurableObject {
       typeof this.resourcesInput === "function" ? this.resourcesInput(this.doEnv) : (this.resourcesInput ?? {}),
     ));
   }
+  // Wire outbound connections once (network I/O the constructor can't await):
+  // their tools merge into this.tools BEFORE any session is constructed — the
+  // ready() callers hoist this ahead of resolveSession. A failed connection is
+  // reported and skipped (connectAll never throws), matching native assembly.
+  private resolveConnections(): Promise<void> {
+    return (this.connectionsOpened ??= (async () => {
+      if (!this.connectionsInput?.length) return;
+      const { actions, report } = await connectAll(this.connectionsInput);
+      for (const r of report) {
+        if (r.error) console.error(`[june] agent "${this.name}": connection "${r.name}" (${r.url}) failed: ${r.error}`);
+      }
+      const seen = new Set(this.tools.map((t) => t.spec.name));
+      for (const a of actions) {
+        const tool = actionToTool(a);
+        if (seen.has(tool.spec.name)) {
+          throw new Error(`AgentDurableObject(${this.name}): duplicate tool name "${tool.spec.name}" from a connection — rename so dispatch is unambiguous.`);
+        }
+        seen.add(tool.spec.name);
+        this.tools.push(tool);
+      }
+    })());
+  }
+  // Everything a turn needs opened BEFORE its synchronous scope-and-subscribe
+  // section: resources (possibly an async provider) and outbound connections.
+  private async ready(): Promise<Resources> {
+    const [resources] = await Promise.all([this.resolveResources(), this.resolveConnections()]);
+    return resources;
+  }
   constructor(state: DurableObjectState, def: DoAgentDef) {
     assertCoreRuntimeVersion(`AgentDurableObject(${def.name ?? "agent"})`); // #94: fail power-on, not mid-turn
     const store = new DoSessionStore(state.storage);
     const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
     this.resourcesInput = def.resources;
+    this.connectionsInput = def.connections;
     this.doEnv = def.env;
     this.services = def.services;
     const name = def.name ?? "agent";
@@ -335,6 +378,18 @@ export class AgentDurableObject {
     this.tools = tools;
     this.channels = channels;
     this.channelInstructions = def.channelInstructions;
+    // Orphan-policy check (#149): assembly can't validate surface keys against
+    // factory channels (they resolve only here, with env) — so warn now, once,
+    // when a policy's source matches no resolved channel. A policy that never
+    // fires is the old silent failure; a warning is its floor.
+    if (def.channelInstructions) {
+      const names = new Set(channels.map((c) => c.name));
+      for (const source of Object.keys(def.channelInstructions)) {
+        if (!names.has(source)) {
+          console.warn(`[june] agent "${name}": surface policy "${source}" matches no channel wired into this DO (${[...names].join(", ") || "none"}) — it will never fire.`);
+        }
+      }
+    }
   }
   // Resolve THE session for this DO: explicit key (from a routed request) → persisted
   // key (a prior life learned it) → "self". A key that contradicts the persisted or
@@ -382,7 +437,7 @@ export class AgentDurableObject {
   // pipeline does; without it runInScope is a pass-through and ambient reads throw.
   async turn(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger; session?: string }): Promise<string> {
     await ensureScope();
-    const resources = await this.resolveResources();
+    const resources = await this.ready();
     const session = this.resolveSession(input.session);
     return runInScope({ resources, services: this.services }, () => session.turn(input));
   }
@@ -392,7 +447,7 @@ export class AgentDurableObject {
   // the default turn-failure log / onTurnError (#76).
   async start(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger; session?: string }): Promise<{ turnId: string }> {
     await ensureScope();
-    const resources = await this.resolveResources();
+    const resources = await this.ready();
     const session = this.resolveSession(input.session);
     return runInScope({ resources, services: this.services }, () => session.start(input));
   }
@@ -450,7 +505,7 @@ export class AgentDurableObject {
       // db/services (ALS propagates to the .then continuation registered here); subscribing
       // happens synchronously right after, before any event can emit. Resources resolve
       // BEFORE this block — the section from start() to the subscription stays synchronous.
-      const resources = await this.resolveResources();
+      const resources = await this.ready();
       let session: AgentSession;
       let started: { turnId: string };
       try {
@@ -535,7 +590,7 @@ export class AgentDurableObject {
       }
       // Same discipline as /turn: resolve resources before the synchronous
       // resume-then-subscribe section.
-      const resources = await this.resolveResources();
+      const resources = await this.ready();
       let session: AgentSession;
       try {
         session = this.resolveSession(key);