effect-agent 0.1.0-beta.9 → 0.1.0-beta.91

package/src/engine/MessagingHost.ts

@@ -0,0 +1,110 @@
+import { Context, type Effect } from "effect";
+
+import type { AnyDefinition } from "../core/Agent.ts";
+import type { ThreadId } from "../core/Identifiers.ts";
+import {
+  type InboxPage,
+  type MessageAddress,
+  type MessageRef,
+  type MessageStatus,
+  MessagingError,
+} from "../core/Messaging.ts";
+import type { IdempotencyKey, Principal } from "../core/Receipt.ts";
+import type { WorkerSource } from "../core/Worker.ts";
+
+export interface PeerTarget {
+  readonly name: string;
+  readonly target: AnyDefinition;
+}
+
+/** A fixed declaration chooses the route. Caller input never selects a destination Thread. */
+export interface SendPeerMessage extends PeerTarget {
+  readonly encodedInput: unknown;
+  readonly idempotencyKey: IdempotencyKey;
+  /** Correlation on sends; replies additionally resolve and authorize the recorded return address. */
+  readonly inReplyTo?: MessageRef;
+}
+
+/** Trusted per-invocation facet. It carries caller authority without exposing it in Tool schemas. */
+export class MessagingHost extends Context.Service<
+  MessagingHost,
+  {
+    readonly context: Effect.Effect<WorkerSource, MessagingError>;
+    readonly send: (request: SendPeerMessage) => Effect.Effect<MessageStatus, MessagingError>;
+    readonly reply: (
+      request: SendPeerMessage & { readonly inReplyTo: MessageRef },
+    ) => Effect.Effect<MessageStatus, MessagingError>;
+    readonly inbox: (
+      request: PeerTarget & { readonly after?: number; readonly limit: number },
+    ) => Effect.Effect<InboxPage, MessagingError>;
+    readonly inspect: (
+      request: PeerTarget & { readonly message: MessageRef },
+    ) => Effect.Effect<MessageStatus, MessagingError>;
+    readonly retry: (
+      request: PeerTarget & { readonly message: MessageRef },
+    ) => Effect.Effect<MessageStatus, MessagingError>;
+  }
+>()("@effect-agent/engine/MessagingHost") {
+  static readonly unavailable: MessagingHost["Service"] = {
+    context: MessagingError.make({ operation: "context", reason: "unavailable" }),
+    send: () => MessagingError.make({ operation: "send", reason: "unavailable" }),
+    reply: () => MessagingError.make({ operation: "reply", reason: "unavailable" }),
+    inbox: () => MessagingError.make({ operation: "inbox", reason: "unavailable" }),
+    inspect: () => MessagingError.make({ operation: "inspect", reason: "unavailable" }),
+    retry: () => MessagingError.make({ operation: "retry", reason: "unavailable" }),
+  };
+
+  /** Runtime-owned per-call binding. Unconfigured Runs deny peer operations. */
+  static readonly forTool = Context.Reference<
+    (source: Extract<WorkerSource, { readonly _tag: "tool" }>) => MessagingHost["Service"]
+  >("@effect-agent/engine/MessagingHost/forTool", {
+    defaultValue: () => () => MessagingHost.unavailable,
+  });
+}
+
+/** Separate context, history, send and management grants; incoming messages grant none of them. */
+export interface PeerAuthorizationRequest {
+  readonly source: MessageAddress;
+  readonly principal: Principal;
+  readonly operation: MessagingError["operation"];
+  readonly access: "context" | "read" | "send" | "control";
+  readonly peerName?: string;
+  readonly destination?: MessageAddress;
+}
+
+export const PeerAuthorizer = Context.Reference<{
+  /** Return the stable delivery principal for sends. It is retained with the frozen envelope. */
+  readonly authorize: (
+    request: PeerAuthorizationRequest,
+  ) => Effect.Effect<Principal, MessagingError>;
+}>("@effect-agent/thread/PeerAuthorizer", {
+  defaultValue: () => ({
+    authorize: (request) => MessagingError.make({ operation: request.operation, reason: "denied" }),
+  }),
+});
+
+/** Application-owned routing; the target Agent is resolved from the existing exact registrations. */
+export const PeerRoutes = Context.Reference<{
+  readonly resolve: (request: {
+    readonly source: MessageAddress;
+    readonly principal: Principal;
+    readonly peerName: string;
+    readonly targetAgentId: MessageAddress["agentId"];
+  }) => Effect.Effect<ThreadId, MessagingError>;
+}>("@effect-agent/thread/PeerRoutes", {
+  defaultValue: () => ({
+    resolve: () => MessagingError.make({ operation: "send", reason: "route-unavailable" }),
+  }),
+});
+
+/** Retry windows are finite; exhaustion parks the retained envelope for explicit authorized retry. */
+export const PeerDeliveryLifetime = Context.Reference<number>(
+  "@effect-agent/thread/PeerDeliveryLifetime",
+  { defaultValue: () => 86_400_000 },
+);
+
+/** Bound canonical send intents across all peers and principals in one source Thread. */
+export const PeerMessageCapacity = Context.Reference<number>(
+  "@effect-agent/thread/PeerMessageCapacity",
+  { defaultValue: () => 256 },
+);

package/src/engine/Output.ts

@@ -0,0 +1,2 @@
+/** Schema-owned final-output formats for Agent definitions. */
+export { textOutput as text } from "./internal/output-contract.ts";

package/src/engine/RunEventSink.ts

@@ -0,0 +1,132 @@
+import { Context, Schema } from "effect";
+import type { Effect } from "effect";
+
+import {
+  type AgentId,
+  type ThreadId,
+  type DelegationId,
+  type RunId,
+  type ToolCallId,
+} from "../core/Identifiers.ts";
+import { type DelegationDepth } from "../core/SubagentContract.ts";
+import { type RunTotals } from "../core/Usage.ts";
+
+/**
+ * Shared identity carried by every pre-base Subagent event payload. The
+ * emitting Tool handler supplies delegation lineage and its own Tool Call
+ * identity; the engine stamps the remaining fields it is authoritative for
+ * (`eventVersion`, `runId`, `threadId`, `agentId`, `sequence`,
+ * `timestamp`, and the emitting batch's `turnId`) when the payload is woven
+ * into the parent stream.
+ */
+export interface SubagentEventBasePayload {
+  readonly toolCallId: ToolCallId;
+  readonly delegationId: DelegationId;
+  readonly childThreadId: ThreadId;
+  readonly childRunId: RunId;
+  readonly targetAgentId: AgentId;
+  readonly depth: DelegationDepth;
+}
+
+/** Pre-base payload for the core `SubagentRequested` event. */
+export interface SubagentRequestedPayload extends SubagentEventBasePayload {
+  readonly _tag: "SubagentRequested";
+}
+
+/** Pre-base payload for the core `SubagentStarted` event. */
+export interface SubagentStartedPayload extends SubagentEventBasePayload {
+  readonly _tag: "SubagentStarted";
+}
+
+/** Pre-base payload for the core `SubagentProgress` event; `summary` is at most 4096 characters. */
+export interface SubagentProgressPayload extends SubagentEventBasePayload {
+  readonly _tag: "SubagentProgress";
+  readonly summary: string;
+}
+
+/** Pre-base payload for the core `SubagentCompleted` event; `turns` is a positive integer. */
+export interface SubagentCompletedPayload extends SubagentEventBasePayload {
+  readonly _tag: "SubagentCompleted";
+  readonly turns: number;
+  readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
+  /** Dimension that bound when the child settled budget-exhausted (the RUN-021 grant-flow marker). */
+  readonly exhausted?: "tokens" | "tool-calls" | "turns" | undefined;
+  /** What the child spent, so a parent can account for delegated work. */
+  readonly usage?: RunTotals | undefined;
+  readonly delegatedUsage?: RunTotals | undefined;
+}
+
+/** Pre-base payload for the core `SubagentFailed` event; `message` is at most 4096 characters. */
+export interface SubagentFailedPayload extends SubagentEventBasePayload {
+  readonly _tag: "SubagentFailed";
+  readonly usage?: RunTotals | undefined;
+  readonly delegatedUsage?: RunTotals | undefined;
+  readonly errorTag: string;
+  readonly message: string;
+}
+
+/** Pre-base payload for the core `SubagentInterrupted` event; `reason` is at most 4096 characters. */
+export interface SubagentInterruptedPayload extends SubagentEventBasePayload {
+  readonly _tag: "SubagentInterrupted";
+  readonly usage?: RunTotals | undefined;
+  readonly delegatedUsage?: RunTotals | undefined;
+  readonly reason: string;
+}
+
+/** Pre-base payload for the core `SubagentJoined` event. */
+export interface SubagentJoinedPayload extends SubagentEventBasePayload {
+  readonly _tag: "SubagentJoined";
+  readonly usage?: RunTotals | undefined;
+  readonly delegatedUsage?: RunTotals | undefined;
+}
+
+/**
+ * Discriminated union of pre-base Subagent lifecycle event payloads accepted
+ * by `RunEventSink.emit`. Each variant is the corresponding core `RunEvent`
+ * class minus the base fields the engine stamps. The stamped event is
+ * constructed through the core Schema class, so core field checks (bounded
+ * text, positive turns) still apply; violating them is a defect of the
+ * emitting handler, not an expected failure.
+ */
+export type SubagentEventPayload =
+  | SubagentRequestedPayload
+  | SubagentStartedPayload
+  | SubagentProgressPayload
+  | SubagentCompletedPayload
+  | SubagentFailedPayload
+  | SubagentInterruptedPayload
+  | SubagentJoinedPayload;
+
+/** A handler emitted a Subagent event after its Tool batch had already settled. */
+export class RunEventSinkClosedError extends Schema.TaggedError<RunEventSinkClosedError>()(
+  "RunEventSinkClosedError",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/**
+ * Service value accepted by Tool handlers to emit first-class Subagent
+ * lifecycle events into the parent Run's semantic stream.
+ *
+ * The sink is backed by a bounded queue drained by the Run's own event stream.
+ * A burst may suspend the emitting handler until that internal stream drains
+ * capacity, but an external detached observer cannot backpressure the Tool
+ * batch. Emitting after the owning Tool batch has settled — or outside any
+ * Tool batch — fails closed with `RunEventSinkClosedError`.
+ */
+export interface RunEventSinkService {
+  readonly emit: (payload: SubagentEventPayload) => Effect.Effect<void, RunEventSinkClosedError>;
+}
+
+/**
+ * Engine-owned seam through which Tool handlers emit Subagent lifecycle
+ * events onto the parent Run stream.
+ *
+ * The engine provides this service locally to every Tool batch, bound to that
+ * batch's Run identity and Turn; it is never satisfied from an application
+ * Layer and is excluded from the runtime's public requirements.
+ */
+export class RunEventSink extends Context.Service<RunEventSink, RunEventSinkService>()(
+  "@effect-agent/engine/RunEventSink",
+) {}