effect-agent 0.1.0-beta.15 → 0.1.0-beta.150

package/src/core/Worker.ts

@@ -0,0 +1,240 @@
+import { Schema } from "effect";
+
+import { AgentPolicy } from "./AgentPolicy.ts";
+import { Update } from "./AgentUpdates.ts";
+import * as FailureDiagnostic from "./FailureDiagnostic.ts";
+import { AgentId, DelegationId, RunId, SettlementId, ThreadId, ToolCallId } from "./Identifiers.ts";
+import { MessageStatus } from "./internal/message-status.ts";
+import { IdempotencyKey, Receipt } from "./Receipt.ts";
+import { SubagentExecutionFailure, SubagentGrant } from "./SubagentContract.ts";
+
+/** Assignment output selected through the Definition's runDisposition declaration. */
+export const AssignmentDisposition = Schema.Literals(["completed", "waiting"]);
+export type AssignmentDisposition = typeof AssignmentDisposition.Type;
+
+/** A permanent destination outcome; an ordinary Run completion does not imply this. */
+export const AssignmentTerminal = Schema.Literals(["completed", "failed", "cancelled"]);
+export type AssignmentTerminal = typeof AssignmentTerminal.Type;
+
+/** A reusable child Thread, correlated with its declaration. This value grants no authority. */
+export const WorkerRef = Schema.Struct({
+  schemaVersion: Schema.Literal(1),
+  delegationId: DelegationId,
+  targetAgentId: AgentId,
+  threadId: ThreadId,
+});
+
+export type WorkerRef = typeof WorkerRef.Type;
+
+/** A continuing worker identity and retained first delivery, never an execution handle. */
+export const WorkerStarted = Schema.Struct({
+  worker: WorkerRef,
+  delivery: MessageStatus,
+}).check(
+  Schema.makeFilter(
+    ({ worker, delivery }) =>
+      delivery.receipt === null || worker.threadId === delivery.receipt.threadId,
+  ),
+);
+
+export type WorkerStarted = typeof WorkerStarted.Type;
+
+/** Stable owner command. Reusing its key for a different worker conflicts. */
+export const WorkerStop = Schema.Struct({ worker: WorkerRef, idempotencyKey: IdempotencyKey });
+export type WorkerStop = typeof WorkerStop.Type;
+
+/** The inbox is sealed and active execution has released ownership. External actions are not undone. */
+export const WorkerStopped = WorkerStop;
+export type WorkerStopped = typeof WorkerStopped.Type;
+
+/** A host-authorized Run allowance is independent of the immutable delegation lineage. */
+export const WorkerBudgetScope = Schema.Literals(["source-subtree", "worker-run"]);
+export type WorkerBudgetScope = typeof WorkerBudgetScope.Type;
+
+/** Host-bound caller metadata. Programmatic calls never fabricate Run or Tool Call identities. */
+export const WorkerSource = Schema.Union([
+  Schema.Struct({
+    _tag: Schema.Literal("tool"),
+    agentId: AgentId,
+    threadId: ThreadId,
+    runId: RunId,
+    toolCallId: ToolCallId,
+  }),
+  Schema.Struct({
+    _tag: Schema.Literal("programmatic"),
+    agentId: AgentId,
+    threadId: ThreadId,
+  }),
+]);
+
+export type WorkerSource = typeof WorkerSource.Type;
+
+/** The caller's effective policy and root-relative depth, resolved by its host. */
+export const WorkerContext = Schema.Struct({
+  source: WorkerSource,
+  policy: AgentPolicy,
+  depth: Schema.Natural,
+  grant: Schema.optionalKey(SubagentGrant),
+});
+
+export type WorkerContext = typeof WorkerContext.Type;
+
+/** Admission identity is distinct from canonical input application. */
+export const WorkerInput = Schema.Struct({ receipt: Receipt, messageId: IdempotencyKey });
+export type WorkerInput = typeof WorkerInput.Type;
+
+export const WorkerAppliedInput = Schema.Struct({
+  ...WorkerInput.fields,
+  runId: RunId,
+  sequence: Schema.Natural,
+});
+
+/** A Run outcome is not assignment completion. Interpret only a Definition's disposition. */
+export const WorkerRun = Schema.Struct({
+  runId: RunId,
+  hostReceipt: Receipt,
+  outcome: Schema.NullOr(Schema.Literals(["completed", "failed", "aborted"])),
+  disposition: Schema.NullOr(Schema.Json),
+});
+
+/** Bounded durable listing data; a latest Receipt never substitutes for a requested Receipt. */
+export const WorkerSummary = Schema.Struct({
+  worker: WorkerRef,
+  latestReceipt: Schema.NullOr(Receipt),
+  /** stopping/stopped identify an owner-issued worker stop, never an ordinary Receipt abort. */
+  state: Schema.Literals([
+    "starting",
+    "active",
+    "idle",
+    "stopping",
+    "stopped",
+    "completed",
+    "failed",
+    "cancelled",
+  ]),
+  acceptedInput: Schema.NullOr(WorkerInput),
+  appliedInput: Schema.NullOr(WorkerAppliedInput),
+  run: Schema.NullOr(WorkerRun),
+  /** One retained unadmitted input, if any; its state is independent of destination execution. */
+  pendingDelivery: Schema.NullOr(MessageStatus),
+  /** Consistent destination facts; pending delivery has its own source-owned version. */
+  watermark: Schema.Struct({
+    canonicalSequence: Schema.Natural,
+    acceptedQueueSequence: Schema.Natural,
+    pendingDeliveryVersion: Schema.NullOr(Schema.Natural),
+  }),
+});
+
+export type WorkerSummary = typeof WorkerSummary.Type;
+
+export const WorkerPage = Schema.Struct({
+  items: Schema.Array(WorkerSummary).check(Schema.isMaxLength(100)),
+  next: Schema.NullOr(ThreadId),
+});
+
+export type WorkerPage = typeof WorkerPage.Type;
+
+/** Authorized canonical history, encoded independently of storage-adapter representations. */
+export const WorkerHistoryEntry = Schema.Struct({
+  sequence: Schema.Natural.check(Schema.isGreaterThan(0)),
+  recordId: Schema.NonEmptyString.check(Schema.isMaxLength(1_024)),
+  record: Schema.Json,
+});
+
+export type WorkerHistoryEntry = typeof WorkerHistoryEntry.Type;
+
+/**
+ * Closed host-boundary failures. Original causes stay private and survive diagnostic transport.
+ * Retained delivery states are successful MessageStatus values, including pending and refused.
+ * After a storage failure, keep the same idempotency key and parameters when reconciling.
+ */
+export class WorkerError extends Schema.TaggedError<WorkerError>()("WorkerError", {
+  cause: Schema.optionalKey(FailureDiagnostic.Value),
+  stack: Schema.optionalKey(Schema.String),
+  /** Concurrency pressure may clear without changing the request. */
+  retryable: Schema.optionalKey(Schema.Literal(true)),
+  operation: Schema.Literals([
+    "context",
+    "start",
+    "followUp",
+    "inspect",
+    "observe",
+    "await",
+    "list",
+    "cancel",
+    "stop",
+  ]),
+  reason: Schema.Literals([
+    "denied",
+    "declaration-unavailable",
+    "worker-mismatch",
+    "receipt-mismatch",
+    "message-mismatch",
+    "idempotency-conflict",
+    "capacity",
+    "not-found",
+    // Decode earlier failures without emitting them for retained deliveries.
+    "delivery-pending",
+    "storage",
+    "corrupt",
+    "unavailable",
+  ]),
+}) {}
+
+export { WorkerOperationTool } from "./SubagentContract.ts";
+
+/** One projected canonical Run outcome. Joined receipts share this identity. */
+export const WorkerReport = <Success extends Schema.Top>(success: Success) => {
+  const identity = {
+    _tag: Schema.Literal("Settled"),
+    worker: WorkerRef,
+    receipt: Receipt,
+    runId: RunId,
+    settlementId: SettlementId,
+  };
+
+  return Schema.Union([
+    // Union preserves the Success codec while making the result field required.
+    Schema.Struct({
+      ...identity,
+      outcome: Schema.Literal("completed"),
+      result: Schema.Union([success]),
+    }),
+    Schema.Struct({
+      ...identity,
+      outcome: Schema.Literals(["failed", "aborted"]),
+      failure: SubagentExecutionFailure,
+    }),
+  ]);
+};
+
+export type WorkerReport<Success extends Schema.Top> = ReturnType<
+  typeof WorkerReport<Success>
+>["Type"];
+
+/** Framework message stored separately from the parent's application input. */
+export const WorkerCompletion = Schema.Struct({
+  _tag: Schema.Literal("WorkerCompletion"),
+  budgetExhausted: Schema.Boolean,
+  schemaVersion: Schema.Literal(1),
+  report: WorkerReport(Schema.Json),
+}).check(Schema.makeFilter(({ report }) => report.worker.threadId === report.receipt.threadId));
+
+export type WorkerCompletion = typeof WorkerCompletion.Type;
+
+/** Source-worker intermediate output, kept separate from application input. */
+export const WorkerUpdate = Schema.Struct({
+  _tag: Schema.Literal("WorkerUpdate"),
+  schemaVersion: Schema.Literal(1),
+  worker: WorkerRef,
+  update: Update,
+}).check(
+  Schema.makeFilter(
+    ({ worker, update }) =>
+      worker.threadId === update.threadId && worker.targetAgentId === update.agentId,
+  ),
+);
+
+export type WorkerUpdate = typeof WorkerUpdate.Type;
+export const FrameworkMessage = Schema.Union([WorkerCompletion, WorkerUpdate]);
+export type FrameworkMessage = typeof FrameworkMessage.Type;

package/src/core/internal/agent-updates.ts

@@ -0,0 +1,34 @@
+import { Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+
+import { Emitter, UpdateError } from "../AgentUpdates.ts";
+
+/** Definition-owned native Tool. Runtime supplies its handler under the same identity. */
+export const updateTool = <S extends Schema.Top>(schema: S) =>
+  Tool.make("emit_update", {
+    description:
+      "Emit a structured intermediate update. Success acknowledges acceptance by this Run; " +
+      "parent delivery and processing are separate. This does not complete the task.",
+    parameters: Schema.Struct({ value: schema }),
+    success: Schema.Struct({ emitted: Schema.Literal(true) }),
+    failure: UpdateError,
+    failureMode: "return",
+  }).addDependency(Emitter);
+
+export type UpdateToolkit<
+  T extends Toolkit.Any,
+  S extends Schema.Top | undefined,
+> = S extends Schema.Top
+  ? Toolkit.Toolkit<T["tools"] & { readonly emit_update: ReturnType<typeof updateTool<S>> }>
+  : T;
+
+export const withUpdateTool = (
+  toolkit: Toolkit.Any,
+  schema: Schema.Top | undefined,
+): Toolkit.Any => {
+  if (schema === undefined) return toolkit;
+  if (Object.hasOwn(toolkit.tools, "emit_update"))
+    throw new TypeError("emit_update is reserved for Agent updates");
+
+  return Toolkit.make(...Object.values(toolkit.tools), updateTool(schema));
+};

package/src/core/internal/message-status.ts

@@ -0,0 +1,60 @@
+import { Schema } from "effect";
+
+import { SettlementId, ThreadId } from "../Identifiers.ts";
+import { IdempotencyKey, Receipt } from "../Receipt.ts";
+
+/** A retained outbound delivery identity, not a destination Receipt or access grant. */
+export const MessageRef = Schema.Struct({ ownerThreadId: ThreadId, messageId: IdempotencyKey });
+export type MessageRef = typeof MessageRef.Type;
+
+const Reason = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+const identity = { message: MessageRef };
+
+/**
+ * Source-owned delivery evidence. Pending confirms retention only; accepted supplies the
+ * destination Receipt, and processed supplies its canonical settlement. Neither retention nor
+ * acceptance proves execution. Refused is a definite rejection; parked stops automatic retry
+ * while retaining the same identity and any acceptance evidence. Inspect instead of resending.
+ */
+export const MessageStatus = Schema.Union([
+  Schema.Struct({
+    ...identity,
+    status: Schema.Literal("pending"),
+    receipt: Schema.Null,
+    settlement: Schema.Null,
+    reason: Schema.NullOr(Reason),
+  }),
+  Schema.Struct({
+    ...identity,
+    status: Schema.Literal("accepted"),
+    receipt: Receipt,
+    settlement: Schema.Null,
+    reason: Schema.NullOr(Reason),
+  }),
+  Schema.Struct({
+    ...identity,
+    status: Schema.Literal("processed"),
+    receipt: Receipt,
+    settlement: Schema.Struct({
+      settlementId: SettlementId,
+      outcome: Schema.Literals(["completed", "failed", "aborted"]),
+    }),
+    reason: Schema.Null,
+  }),
+  Schema.Struct({
+    ...identity,
+    status: Schema.Literal("refused"),
+    receipt: Schema.Null,
+    settlement: Schema.Null,
+    reason: Reason,
+  }),
+  Schema.Struct({
+    ...identity,
+    status: Schema.Literal("parked"),
+    receipt: Schema.NullOr(Receipt),
+    settlement: Schema.Null,
+    reason: Reason,
+  }),
+]);
+
+export type MessageStatus = typeof MessageStatus.Type;

package/src/core/internal/strict-schema.ts

@@ -0,0 +1,14 @@
+import { Schema, SchemaParser, SchemaTransformation } from "effect";
+
+/** Keep strict parsing on nested values even when an outer parser uses its defaults. */
+export const strictSchema = <S extends Schema.Top>(schema: S) =>
+  Schema.declareConstructor<S["Type"], S["Encoded"]>()(
+    [schema],
+    ([codec]) =>
+      (value, _ast, options) =>
+        SchemaParser.decodeUnknownEffect(codec)(value, { ...options, onExcessProperty: "error" }),
+    {
+      toCodecJson: ([codec]) =>
+        Schema.link<S["Encoded"]>()(codec, SchemaTransformation.passthrough()),
+    },
+  );

package/src/core/internal/utf8.ts

@@ -0,0 +1,23 @@
+/** UTF-8 width, including the replacement encoding used for lone UTF-16 surrogates. */
+export const codePointUtf8Length = (codePoint: number): number => {
+  if (codePoint < 0x80) return 1;
+  if (codePoint < 0x800) return 2;
+  if (codePoint < 0x10000) return 3;
+
+  return 4;
+};
+
+/** Count encoded bytes without allocating an encoded copy of the text. */
+export const utf8ByteLength = (value: string): number => {
+  let bytes = 0;
+  let index = 0;
+
+  while (index < value.length) {
+    const codePoint = value.codePointAt(index) ?? 0;
+
+    bytes += codePointUtf8Length(codePoint);
+    index += codePoint > 0xffff ? 2 : 1;
+  }
+
+  return bytes;
+};

package/src/durable/ActivityStore.ts

@@ -0,0 +1,160 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+import { ThreadId } from "../core/Identifiers.ts";
+import { CanonicalSequence, Digest, PersistedJson, RecordId } from "./Records.ts";
+
+const Identity = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+const Epoch = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }));
+const Timestamp = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));
+
+/** Application-owned processor identity. Changing the version starts independent progress. */
+export class ActivityProcessorKey extends Schema.Class<ActivityProcessorKey>(
+  "@effect-agent/thread/ActivityProcessorKey",
+)({
+  processorId: Identity,
+  processorVersion: Identity,
+  threadId: ThreadId.check(Schema.isMaxLength(1_024)),
+}) {}
+
+/** Durable extraction output, pinned before any external application of that output. */
+export class PreparedActivity extends Schema.Class<PreparedActivity>(
+  "@effect-agent/thread/PreparedActivity",
+)({
+  version: Schema.Literal(1),
+  key: ActivityProcessorKey,
+  sequence: CanonicalSequence.check(Schema.isGreaterThan(0)),
+  workId: Digest,
+  recordId: RecordId,
+  recordDigest: Digest,
+  output: PersistedJson,
+}) {}
+
+/** Independent from Thread ownership, submission delivery, and canonical checkpoints. */
+export class ActivityClaim extends Schema.Class<ActivityClaim>(
+  "@effect-agent/thread/ActivityClaim",
+)({
+  key: ActivityProcessorKey,
+  owner: Identity,
+  epoch: Epoch,
+  throughSequence: CanonicalSequence,
+  leaseExpiresAt: Timestamp,
+  /** Pending output captured atomically at acquisition; advance returns null here. */
+  pending: Schema.NullOr(PreparedActivity),
+}) {}
+
+export class ActivityProgress extends Schema.Class<ActivityProgress>(
+  "@effect-agent/thread/ActivityProgress",
+)({
+  version: Schema.Literal(1),
+  key: ActivityProcessorKey,
+  throughSequence: CanonicalSequence,
+  epoch: Epoch,
+  owner: Schema.NullOr(Identity),
+  leaseExpiresAt: Timestamp,
+  pending: Schema.NullOr(PreparedActivity),
+  /** Time of the last cursor advance, not the activity time or a global freshness clock. */
+  advancedAt: Schema.NullOr(Timestamp),
+}) {}
+
+export class ActivityStoreError extends Schema.TaggedError<ActivityStoreError>()(
+  "ActivityStoreError",
+  {
+    operation: Schema.NonEmptyString,
+    reason: Schema.Literals(["invalid-input", "unavailable", "corrupt", "incompatible"]),
+  },
+) {}
+
+export class ActivityBusy extends Schema.TaggedError<ActivityBusy>()("ActivityBusy", {
+  key: ActivityProcessorKey,
+  leaseExpiresAt: Timestamp,
+}) {}
+
+export class ActivityOwnershipLost extends Schema.TaggedError<ActivityOwnershipLost>()(
+  "ActivityOwnershipLost",
+  { key: ActivityProcessorKey, owner: Identity, epoch: Epoch },
+) {}
+
+export class ActivityWorkConflict extends Schema.TaggedError<ActivityWorkConflict>()(
+  "ActivityWorkConflict",
+  { key: ActivityProcessorKey, workId: Digest },
+) {}
+
+export const ActivityMutationPoint = Schema.Literals([
+  "activity:initialize:before",
+  "activity:initialize:after",
+  "activity:claim:before",
+  "activity:claim:after-state",
+  "activity:claim:after",
+  "activity:prepare:before",
+  "activity:prepare:after-state",
+  "activity:prepare:after",
+  "activity:advance:before",
+  "activity:advance:after-state",
+  "activity:advance:after",
+  "activity:release:before",
+  "activity:release:after-state",
+  "activity:release:after",
+]);
+
+export type ActivityMutationPoint = typeof ActivityMutationPoint.Type;
+
+export class ActivityMutationFailure extends Schema.TaggedError<ActivityMutationFailure>()(
+  "ActivityMutationFailure",
+  { point: ActivityMutationPoint },
+) {}
+
+export class ActivityMutationFailpoint extends Context.Service<
+  ActivityMutationFailpoint,
+  { readonly hit: (point: ActivityMutationPoint) => Effect.Effect<void, ActivityMutationFailure> }
+>()("@effect-agent/thread/ActivityMutationFailpoint") {
+  static readonly layer = Layer.succeed(this, { hit: () => Effect.void });
+}
+
+export type ActivityStoreFailure =
+  | ActivityStoreError
+  | ActivityBusy
+  | ActivityOwnershipLost
+  | ActivityWorkConflict
+  | ActivityMutationFailure;
+
+export class ActivityClaimRequest extends Schema.Class<ActivityClaimRequest>(
+  "@effect-agent/thread/ActivityClaimRequest",
+)({
+  key: ActivityProcessorKey,
+  owner: Identity,
+  leaseMillis: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 600_000 })),
+}) {}
+
+/**
+ * Optional durable progress for finite committed-activity passes. Every mutation is atomic.
+ * claim rejects an unexpired owner and allocates a strictly newer epoch on every successful
+ * acquisition, including an initial grant and reacquisition after release with the same owner. It preserves
+ * pending output and returns it with the claim. prepare and advance reject expired or superseded claims and
+ * require the claim's throughSequence to equal current progress. prepare accepts only the next
+ * sequence, pins one output, and rejects divergent reuse. advance requires its pending work ID,
+ * increments progress by exactly one, and clears pending in the same transaction.
+ *
+ * release checks owner/epoch, independent of the cursor, and never discards pending output.
+ * The adapter owns its lease clock. A failed release leaves only a bounded lease to expire.
+ * This port never owns, mutates, or checkpoints the canonical Thread log.
+ */
+export class ActivityProcessorStore extends Context.Service<
+  ActivityProcessorStore,
+  {
+    readonly inspect: (
+      key: ActivityProcessorKey,
+    ) => Effect.Effect<ActivityProgress | null, ActivityStoreError>;
+    readonly claim: (
+      request: ActivityClaimRequest,
+    ) => Effect.Effect<ActivityClaim, ActivityStoreFailure>;
+    readonly prepare: (request: {
+      readonly claim: ActivityClaim;
+      readonly work: PreparedActivity;
+    }) => Effect.Effect<PreparedActivity, ActivityStoreFailure>;
+    readonly advance: (request: {
+      readonly claim: ActivityClaim;
+      readonly workId: Digest;
+    }) => Effect.Effect<ActivityClaim, ActivityStoreFailure>;
+    readonly release: (claim: ActivityClaim) => Effect.Effect<void, ActivityStoreFailure>;
+  }
+>()("@effect-agent/thread/ActivityProcessorStore") {}