@xandreed/plugin-tasks 0.0.0-stage → 0.8.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xand Reed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @xandreed/plugin-tasks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Efferent composable agent framework, 0.8.0-next.0. Bun on Linux.
+
+Documentation: https://github.com/xandreeddev/efferent

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { tasksPlugin, TasksPluginLive, default } from "./plugin.adapter.js";
+export { TasksLive } from "./tasks.adapter.js";
+export { InProcessTaskRunnerLive } from "./task-runner.adapter.js";
+export { tasksCapability } from "./tasks-capability.adapter.js";
+export { TASK_CANCELLED, TASK_RESULT, TASK_STARTED, TaskCancelled, TaskOutcome, TaskResult, TaskStarted, TasksConfig, tasksDefaults } from "./task-records.entity.js";
+export { deliveryId, noticeOf } from "./task.entity.functions.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { tasksPlugin, TasksPluginLive, default } from "./plugin.adapter.js";
+export { TasksLive } from "./tasks.adapter.js";
+export { InProcessTaskRunnerLive } from "./task-runner.adapter.js";
+export { tasksCapability } from "./tasks-capability.adapter.js";
+export { TASK_CANCELLED, TASK_RESULT, TASK_STARTED, TaskCancelled, TaskOutcome, TaskResult, TaskStarted, TasksConfig, tasksDefaults } from "./task-records.entity.js";
+export { deliveryId, noticeOf } from "./task.entity.functions.js";

package/dist/plugin.adapter.d.ts

@@ -0,0 +1,27 @@
+import { Layer } from "effect";
+import { Capabilities, Sessions, TaskExecutor, TaskRunner, Tasks } from "@xandreed/core";
+/**
+ * Background tasks: a task is one turn of a child session, run by the
+ * host's TaskRunner and TaskExecutor, its result delivered to the parent's
+ * inbox for the turn after the one in flight. With `tools`, the model gets
+ * `start_task` and `task_status`.
+ */
+export declare const tasksPlugin: import("@xandreed/core").TypedPlugin<{
+    readonly maxRunning: number;
+    readonly tools: boolean;
+    readonly replyChars: number;
+    readonly closingReserveMs: number;
+}, {
+    readonly maxRunning: number;
+    readonly tools: boolean;
+    readonly replyChars: number;
+    readonly closingReserveMs: number;
+}, Capabilities | Tasks, never, Sessions | TaskRunner | TaskExecutor>;
+/** Background tasks as a typed layer: provides Tasks (and, with `tools`, their capability); requires Sessions, TaskRunner and TaskExecutor. */
+export declare const TasksPluginLive: (options?: Partial<{
+    readonly maxRunning: number;
+    readonly tools: boolean;
+    readonly replyChars: number;
+    readonly closingReserveMs: number;
+}> | undefined) => Layer.Layer<Capabilities | Tasks, import("@xandreed/core").HarnessError, Sessions | TaskRunner | TaskExecutor>;
+export default tasksPlugin;

package/dist/plugin.adapter.js

@@ -0,0 +1,17 @@
+import { Layer } from "effect";
+import { Capabilities, definePlugin, Sessions, TaskExecutor, TaskRunner, Tasks } from "@xandreed/core";
+import { tasksCapability } from "./tasks-capability.adapter.js";
+import { TasksConfig, tasksDefaults } from "./task-records.entity.js";
+import { TasksLive } from "./tasks.adapter.js";
+export const tasksPlugin = definePlugin({
+  id: "@xandreed/plugin-tasks",
+  version: "0.8.0-next.0",
+  scope: "runtime",
+  config: TasksConfig,
+  defaults: tasksDefaults,
+  requires: [Sessions, TaskRunner, TaskExecutor],
+  provides: [Tasks],
+  contributes: [Capabilities],
+  layer: (config) => Layer.mergeAll(TasksLive(config), Layer.succeed(Capabilities, config.tools ? [tasksCapability] : []))
+}), TasksPluginLive = tasksPlugin.live;
+export default tasksPlugin;

package/dist/task-records.entity.d.ts

@@ -0,0 +1,47 @@
+import { Schema } from "effect";
+export declare const TASK_STARTED = "task.started";
+export declare const TASK_RESULT = "task.result";
+export declare const TASK_CANCELLED = "task.cancelled";
+export declare const TaskStarted: Schema.Struct<{
+    readonly taskId: Schema.brand<Schema.String, "ConversationId">;
+    readonly instructions: Schema.String;
+    readonly mode: Schema.Literals<readonly ["fork", "spawn"]>;
+    /** The starter's own facts (e.g. the run that started it). */
+    readonly meta: Schema.$Record<Schema.String, Schema.Unknown>;
+}>;
+export type TaskStarted = typeof TaskStarted.Type;
+export declare const TaskOutcome: Schema.Literals<readonly ["completed", "partial", "failed", "interrupted"]>;
+export type TaskOutcome = typeof TaskOutcome.Type;
+export declare const TaskFailure: Schema.Struct<{
+    readonly code: Schema.String;
+    readonly message: Schema.String;
+}>;
+export declare const TaskResult: Schema.Struct<{
+    readonly taskId: Schema.brand<Schema.String, "ConversationId">;
+    readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed", "interrupted"]>;
+    readonly reply: Schema.OptionFromNullOr<Schema.String>;
+    readonly failure: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly code: Schema.String;
+        readonly message: Schema.String;
+    }>>;
+}>;
+export type TaskResult = typeof TaskResult.Type;
+export declare const TaskCancelled: Schema.Struct<{
+    readonly taskId: Schema.brand<Schema.String, "ConversationId">;
+}>;
+export declare const TasksConfig: Schema.Struct<{
+    /** Tasks a session may have waiting or running at once. */
+    readonly maxRunning: Schema.Int;
+    /** Offer the model `start_task` and `task_status`. */
+    readonly tools: Schema.Boolean;
+    /** A longer result reaches the parent cut to this many characters. */
+    readonly replyChars: Schema.Int;
+    /**
+     * Of a runner's finite budget, the time execution leaves for what follows
+     * it: the child's result and ending, the delivery and the parent's
+     * closing commits (several store round trips). At most half the budget.
+     */
+    readonly closingReserveMs: Schema.Int;
+}>;
+export type TasksConfig = typeof TasksConfig.Type;
+export declare const tasksDefaults: TasksConfig;

package/dist/task-records.entity.js

@@ -0,0 +1,18 @@
+import { Schema } from "effect";
+import { ConversationId, JsonObject, TaskMode } from "@xandreed/core";
+export const TASK_STARTED = "task.started", TASK_RESULT = "task.result", TASK_CANCELLED = "task.cancelled", TaskStarted = Schema.Struct({
+  taskId: ConversationId,
+  instructions: Schema.String,
+  mode: TaskMode,
+  meta: JsonObject
+}), TaskOutcome = Schema.Literals(["completed", "partial", "failed", "interrupted"]), TaskFailure = Schema.Struct({ code: Schema.String, message: Schema.String }), TaskResult = Schema.Struct({
+  taskId: ConversationId,
+  outcome: TaskOutcome,
+  reply: Schema.OptionFromNullOr(Schema.String),
+  failure: Schema.OptionFromNullOr(TaskFailure)
+}), TaskCancelled = Schema.Struct({ taskId: ConversationId }), TasksConfig = Schema.Struct({
+  maxRunning: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 20 })),
+  tools: Schema.Boolean,
+  replyChars: Schema.Int.check(Schema.isBetween({ minimum: 100, maximum: 1e5 })),
+  closingReserveMs: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 600000 }))
+}), tasksDefaults = { maxRunning: 2, tools: !1, replyChars: 12000, closingReserveMs: 2000 };

package/dist/task-runner.adapter.d.ts

@@ -0,0 +1,11 @@
+import { Layer } from "effect";
+import { TaskRunner } from "@xandreed/core";
+/**
+ * Background work on fibers of this process, each on its own fiber (it
+ * keeps none of the starting turn's services), all interrupted when the
+ * layer's scope closes: an interrupted task's turn ends as interrupted.
+ * With `maxMs`, each piece of work must be done that long after it starts.
+ */
+export declare const InProcessTaskRunnerLive: (options?: {
+    readonly maxMs?: number;
+}) => Layer.Layer<TaskRunner>;

package/dist/task-runner.adapter.js

@@ -0,0 +1,11 @@
+import { Clock, Effect, FiberSet, Layer, Option } from "effect";
+import { TaskRunner } from "@xandreed/core";
+export const InProcessTaskRunnerLive = (options) => Layer.effect(TaskRunner, Effect.gen(function* () {
+  const fibers = yield* FiberSet.make(), context = yield* Effect.context();
+  return TaskRunner.of({
+    run: (work) => Effect.gen(function* () {
+      const now = yield* Clock.currentTimeMillis, deadline = Option.map(Option.fromNullishOr(options?.maxMs), (ms) => now + ms), fiber = yield* Effect.sync(() => Effect.runForkWith(context)(work(deadline)));
+      yield* FiberSet.add(fibers, fiber);
+    })
+  });
+}));

package/dist/task.entity.functions.d.ts

@@ -0,0 +1,38 @@
+import { Exit, Option } from "effect";
+import { HarnessError } from "@xandreed/core";
+import type { SessionLogEvent, SessionView, TaskStatus, TaskView, TurnOutcome } from "@xandreed/core";
+import type { TaskResult as Result, TaskStarted as Started } from "./task-records.entity.js";
+/** The inbox id a task's result is delivered under: once per task. */
+export declare const deliveryId: (taskId: string) => string;
+/** Done and worth telling the parent about (a cancelled task tells nothing). */
+export declare const isFinished: (status: TaskStatus) => boolean;
+/** Waiting to run, or running. */
+export declare const isActive: (status: TaskStatus) => boolean;
+/** The tasks a parent started, in order; a record that does not decode is skipped. */
+export declare const startedOf: (events: ReadonlyArray<SessionLogEvent>) => ReadonlyArray<Started>;
+/** The inbox ids a session has had delivered. */
+export declare const deliveredOf: (events: ReadonlyArray<SessionLogEvent>) => ReadonlySet<string>;
+export interface TaskEnd {
+    readonly status: TaskStatus;
+    readonly reply: Option.Option<string>;
+    readonly failure: Option.Option<{
+        readonly code: string;
+        readonly message: string;
+    }>;
+}
+/**
+ * Where a task stands, from its child: the first of its result and its
+ * cancellation ends it; otherwise it runs while its turn is held, was
+ * interrupted if a turn began and closed without a result, and waits if
+ * none began.
+ */
+export declare const endOf: (view: SessionView, records: ReadonlyArray<SessionLogEvent>) => TaskEnd;
+/** A child that no longer exists: its parent's removal took it. */
+export declare const goneEnd: TaskEnd;
+/** How the child's turn went, as its result records it: a turn past its deadline is interrupted. */
+export declare const resultOf: (taskId: Result["taskId"], exit: Exit.Exit<Option.Option<TurnOutcome>, HarnessError>) => Result;
+/**
+ * What the parent's inbox turn shows the model: a trusted frame around the
+ * task's own words, which may not close the frame early.
+ */
+export declare const noticeOf: (task: TaskView, replyChars: number) => string;

package/dist/task.entity.functions.js

@@ -0,0 +1,46 @@
+import { Cause, Exit, Option, Schema } from "effect";
+import { HarnessError } from "@xandreed/core";
+import { TASK_CANCELLED, TASK_RESULT, TASK_STARTED, TaskResult, TaskStarted } from "./task-records.entity.js";
+const decodeStarted = Schema.decodeUnknownOption(TaskStarted), decodeResult = Schema.decodeUnknownOption(TaskResult);
+export const deliveryId = (taskId) => `task:${taskId}`;
+const FINISHED = ["completed", "partial", "failed", "interrupted"];
+export const isFinished = (status) => FINISHED.includes(status), isActive = (status) => status === "pending" || status === "running", startedOf = (events) => events.filter((event) => event.kind === TASK_STARTED).flatMap((event) => Option.toArray(decodeStarted(event.data))), deliveredOf = (events) => new Set(events.filter((event) => event.kind === "inbox.queued").map((event) => String(event.data.id)));
+const began = (view) => view.turns > Option.match(view.header.parent, { onNone: () => 0, onSome: (lineage) => lineage.turnAtFork });
+export const endOf = (view, records) => {
+  const first = records.find((event) => event.kind === TASK_RESULT || event.kind === TASK_CANCELLED);
+  if (first?.kind === TASK_CANCELLED)
+    return { status: "cancelled", reply: Option.none(), failure: Option.none() };
+  const result = first === void 0 ? Option.none() : decodeResult(first.data);
+  if (Option.isSome(result))
+    return { status: result.value.outcome, reply: result.value.reply, failure: result.value.failure };
+  if (Option.isSome(view.open))
+    return { status: "running", reply: Option.none(), failure: Option.none() };
+  return began(view) ? { status: "interrupted", reply: Option.none(), failure: Option.some({ code: "task.lost", message: "the task's turn stopped without a result" }) } : { status: "pending", reply: Option.none(), failure: Option.none() };
+}, goneEnd = { status: "cancelled", reply: Option.none(), failure: Option.some({ code: "task.removed", message: "the task's session was removed" }) }, resultOf = (taskId, exit) => Exit.match(exit, {
+  onSuccess: (outcome) => Option.match(outcome, {
+    onNone: () => ({ taskId, outcome: "interrupted", reply: Option.none(), failure: Option.some({ code: "task.deadline", message: "the task ran out of time" }) }),
+    onSome: (done) => ({
+      taskId,
+      outcome: done.outcome,
+      reply: done.reply,
+      failure: done.outcome === "failed" ? Option.some({ code: "task.turn", message: "the task's turn failed" }) : Option.none()
+    })
+  }),
+  onFailure: (cause) => {
+    const error = Cause.squash(cause);
+    return {
+      taskId,
+      outcome: "failed",
+      reply: Option.none(),
+      failure: Option.some(error instanceof HarnessError ? { code: error.code, message: error.message } : { code: "task.turn", message: "the task's turn failed" })
+    };
+  }
+}), noticeOf = (task, replyChars) => {
+  const output = Option.match(task.reply, {
+    onNone: () => Option.match(task.failure, { onNone: () => "(no reply)", onSome: (failure) => `(no reply: ${failure.message})` }),
+    onSome: (reply) => reply.length > replyChars ? `${reply.slice(0, replyChars)}
+(cut at ${replyChars} characters)` : reply
+  });
+  return [`[Background task ${task.taskId} ${task.status}]`, "<task-output>", output.replaceAll("</task-output>", "</task_output>"), "</task-output>"].join(`
+`);
+};

package/dist/tasks-capability.adapter.d.ts

@@ -0,0 +1,2 @@
+/** The model's way to start background tasks and check on them. */
+export declare const tasksCapability: import("@xandreed/core").Capability;

package/dist/tasks-capability.adapter.js

@@ -0,0 +1,38 @@
+import { Tool } from "effect/ai";
+import { Effect, Option, Schema } from "effect";
+import { defineCapability, defineSkill, defineTool, Failure, RunContext, TaskMode, Tasks, TaskStatus } from "@xandreed/core";
+const StartTask = Tool.make("start_task", {
+  description: "Start a background task: another run of you works on the instructions while this conversation goes on, and its result comes back here when it finishes, for you to answer then. Use it for long work the user need not wait for, and say that you started it. mode fork: the task sees this conversation so far; spawn: it sees only the instructions.",
+  parameters: Schema.Struct({ instructions: Schema.String, mode: TaskMode }),
+  success: Schema.Struct({ taskId: Schema.String, status: TaskStatus }),
+  failure: Failure,
+  failureMode: "return"
+}), TaskStatusTool = Tool.make("task_status", {
+  description: "Check a background task this conversation started: whether it is still running, and its result once it has one.",
+  parameters: Schema.Struct({ taskId: Schema.String }),
+  success: Schema.Struct({ taskId: Schema.String, status: TaskStatus, reply: Schema.NullOr(Schema.String) }),
+  failure: Failure,
+  failureMode: "return"
+}), unavailable = (error) => ({ error: "TasksUnavailable", message: `Background tasks are unavailable right now (${error._tag})` });
+export const tasksCapability = defineCapability({
+  id: "@xandreed/plugin-tasks/tools",
+  version: "1",
+  tools: [
+    defineTool({
+      tool: StartTask,
+      handler: ({ instructions, mode }) => Effect.gen(function* () {
+        const run = yield* RunContext, task = yield* (yield* Tasks).start(run.session, { instructions, mode, meta: { runId: run.runId } }).pipe(Effect.mapError((error) => error._tag === "TaskRefused" ? { error: "TaskRefused", message: error.message } : unavailable(error)));
+        return { taskId: task.taskId, status: task.status };
+      })
+    }),
+    defineTool({
+      tool: TaskStatusTool,
+      handler: ({ taskId }) => Effect.gen(function* () {
+        const run = yield* RunContext, task = yield* (yield* Tasks).status(run.session, taskId).pipe(Effect.mapError((error) => error._tag === "TaskMissing" ? { error: "UnknownTask", message: `No task ${taskId} was started in this conversation` } : unavailable(error)));
+        return { taskId: task.taskId, status: task.status, reply: Option.getOrNull(task.reply) };
+      }),
+      annotations: { readOnly: !0 }
+    })
+  ],
+  skills: [defineSkill({ id: "tasks.background", summary: "Run long work in the background and check on it.", tools: ["start_task", "task_status"], always: !0 })]
+});

package/dist/tasks.adapter.d.ts

@@ -0,0 +1,13 @@
+import { Layer } from "effect";
+import { Sessions, TaskExecutor, TaskRunner, Tasks } from "@xandreed/core";
+import type { TasksConfig } from "./task-records.entity.js";
+/**
+ * Background tasks over Sessions. A task is one turn of a child session
+ * whose id is the task's. Everything that decides reads the log (the
+ * parent's `task.started`, the child's result or cancellation, the parent's
+ * inbox), so any instance, or a later request, can finish what another
+ * left: run a task that never ran, deliver a result that was never
+ * delivered. Delivery is once per task (the inbox id), and whoever delivers
+ * drains the parent, so it reacts after the answer in flight.
+ */
+export declare const TasksLive: (config: TasksConfig) => Layer.Layer<Tasks, never, Sessions | TaskRunner | TaskExecutor>;

package/dist/tasks.adapter.js

@@ -0,0 +1,151 @@
+import { Clock, Effect, Layer, Option, Ref, Schema } from "effect";
+import {
+  ConversationId,
+  HarnessError,
+  MemoryKindOf,
+  SessionLogError,
+  Sessions,
+  TaskExecutor,
+  TaskMissing,
+  TaskRefused,
+  TaskRunner,
+  Tasks,
+  UserMessage
+} from "@xandreed/core";
+import { deliveredOf, deliveryId, endOf, goneEnd, isActive, isFinished, noticeOf, resultOf, startedOf } from "./task.entity.functions.js";
+import { TASK_CANCELLED, TASK_RESULT, TASK_STARTED, TaskResult, TaskStarted } from "./task-records.entity.js";
+const OUTCOME_KINDS = [TASK_RESULT, TASK_CANCELLED], encodeFailure = (error) => new SessionLogError({ code: "tasks.encode", message: error.message }), startedJson = (started) => Schema.encodeEffect(TaskStarted)(started).pipe(Effect.map((data) => data), Effect.mapError(encodeFailure)), resultJson = (result) => Schema.encodeEffect(TaskResult)(result).pipe(Effect.map((data) => data), Effect.mapError(encodeFailure)), reservedAsStorage = (error) => Effect.fail(new SessionLogError({ code: "tasks.kind", message: `${error.kind} is reserved` }));
+export const TasksLive = (config) => Layer.effect(Tasks, Effect.gen(function* () {
+  const sessions = yield* Sessions, runner = yield* TaskRunner, executor = yield* TaskExecutor, childOf = (parent, task) => ({ id: task, owner: parent.owner }), childState = (child) => Effect.all([sessions.get(child), sessions.read(child, { kinds: OUTCOME_KINDS })]).pipe(Effect.map(Option.some), Effect.catchTag("SessionMissing", () => Effect.succeed(Option.none()))), viewOf = (parent, started, delivered) => childState(childOf(parent, started.taskId)).pipe(Effect.map((state) => ({
+    taskId: started.taskId,
+    parent: parent.id,
+    child: started.taskId,
+    instructions: started.instructions,
+    mode: started.mode,
+    ...Option.match(state, { onNone: () => goneEnd, onSome: ([view, records]) => endOf(view, records) }),
+    delivered: delivered.has(deliveryId(started.taskId))
+  }))), parentRecords = (parent) => sessions.read(parent, { kinds: [TASK_STARTED, "inbox.queued"] }), listOf = (parent) => parentRecords(parent).pipe(Effect.flatMap((events) => Effect.forEach(startedOf(events), (started) => viewOf(parent, started, deliveredOf(events))))), taskOf = (parent, taskId) => Effect.gen(function* () {
+    const events = yield* parentRecords(parent), started = startedOf(events).find((record) => record.taskId === taskId);
+    return started === void 0 ? yield* Effect.fail(new TaskMissing({ session: parent.id, taskId })) : yield* viewOf(parent, started, deliveredOf(events));
+  }), recordEnd = (child, result) => sessions.transact(child, () => Effect.gen(function* () {
+    return { drafts: (yield* sessions.read(child, { kinds: OUTCOME_KINDS })).length > 0 ? [] : [{ kind: TASK_RESULT, data: yield* resultJson(result) }], result: void 0 };
+  })).pipe(Effect.catchTag("ReservedKind", reservedAsStorage), Effect.asVoid), bounded = (body, writer, deadline) => Effect.gen(function* () {
+    const now = yield* Clock.currentTimeMillis, timed = Option.match(deadline, {
+      onNone: () => body.pipe(Effect.map(Option.some)),
+      onSome: (at) => body.pipe(Effect.timeoutOption(Math.max(0, at - now)))
+    });
+    return yield* Effect.raceFirst(timed, writer.closed.pipe(Effect.flatMap((closed) => Effect.fail(new HarnessError({ code: "turn.closed", message: `turn ${closed.turn} was ${closed.reason}` })))));
+  }), runChild = (parent, task, deadline) => {
+    const child = childOf(parent, task.child);
+    return Effect.scoped(Effect.gen(function* () {
+      const writer = yield* sessions.begin(child, {
+        _tag: "User",
+        userMessage: new UserMessage({ text: task.instructions }),
+        runId: yield* Effect.sync(() => crypto.randomUUID()),
+        key: deliveryId(task.taskId),
+        command: { task: task.taskId }
+      });
+      if ((yield* sessions.read(child, { kinds: [TASK_CANCELLED] })).length > 0)
+        return yield* writer.end({ reason: "cancelled", failure: Option.none() });
+      const exit = yield* Effect.exit(bounded(executor.turn(writer, { ...task, status: "running" }), writer, deadline)), result = resultOf(task.taskId, exit), data = yield* resultJson(result);
+      yield* writer.transact((foreign) => Effect.succeed({
+        drafts: foreign.some((event) => event.kind === TASK_CANCELLED) ? [] : [{ kind: TASK_RESULT, data }],
+        result: void 0
+      }));
+      return yield* writer.end({ reason: result.outcome, failure: result.failure });
+    })).pipe(Effect.catchTags({
+      SessionBusy: () => Effect.void,
+      TurnDuplicate: () => Effect.void,
+      KeyConflict: () => Effect.void,
+      NothingPending: () => Effect.void,
+      TurnRefused: (refused) => recordEnd(child, {
+        taskId: task.taskId,
+        outcome: "failed",
+        reply: Option.none(),
+        failure: Option.some({ code: "task.refused", message: refused.message })
+      }),
+      HarnessError: (error) => Effect.logInfo(`background task ${task.taskId} stopped: ${error.message}`)
+    }), Effect.asVoid);
+  }, deliverNotice = (parent, task) => sessions.deliver(parent, {
+    id: deliveryId(task.taskId),
+    source: { kind: "task", taskId: task.taskId, child: task.child, status: task.status },
+    content: noticeOf(task, config.replyChars)
+  }).pipe(Effect.catchTag("InboxFull", (full) => Effect.logWarning(`the inbox of ${parent.id} is full; task ${task.taskId} is delivered later`).pipe(Effect.as({ delivered: !1, pending: full.pending })))), noting = (writer, answered) => {
+    const note = (drafts) => drafts.some((draft) => draft.kind === MemoryKindOf.TurnEnded) ? Ref.set(answered, !0) : Effect.void;
+    return {
+      ...writer,
+      append: (drafts) => note(drafts).pipe(Effect.andThen(writer.append(drafts))),
+      transact: (decide) => writer.transact((foreign) => decide(foreign).pipe(Effect.tap((decision) => note(decision.drafts))))
+    };
+  }, reaction = (writer, deadline) => Effect.gen(function* () {
+    const now = yield* Clock.currentTimeMillis;
+    if (Option.isNone(deadline))
+      return yield* executor.react(writer);
+    const cut = { code: "task.deadline", message: "the runner's deadline ended the inbox reaction" };
+    if (deadline.value <= now)
+      return yield* writer.end({ reason: "interrupted", failure: Option.some({ ...cut, message: "the runner's deadline passed before the inbox reaction began" }) });
+    const answered = yield* Ref.make(!1), reacted = yield* executor.react(noting(writer, answered)).pipe(Effect.timeoutOption(deadline.value - now));
+    if (Option.isSome(reacted))
+      return;
+    yield* writer.end({ reason: (yield* Ref.get(answered)) ? "partial" : "interrupted", failure: Option.some(cut) });
+  }), settle = (parent, taskId, deadline) => Effect.gen(function* () {
+    const task = yield* taskOf(parent, taskId);
+    if (!isFinished(task.status) || task.delivered)
+      return;
+    const delivered = yield* deliverNotice(parent, task), now = yield* Clock.currentTimeMillis, remaining = Option.map(deadline, (at) => at - now);
+    if (delivered.pending === 0 || Option.isSome(remaining) && remaining.value <= 0)
+      return;
+    yield* sessions.drain(parent, (writer) => reaction(writer, deadline), Option.isSome(deadline) ? { maxTurns: 1 } : {});
+  }), work = (parent, taskId) => (deadline) => Effect.gen(function* () {
+    const started = yield* Clock.currentTimeMillis, executeBy = Option.map(deadline, (at) => at - Math.min(config.closingReserveMs, Math.floor(Math.max(0, at - started) / 2))), execution = Effect.gen(function* () {
+      const task = yield* taskOf(parent, taskId);
+      if (task.status === "pending")
+        yield* runChild(parent, task, executeBy);
+      yield* settle(parent, taskId, executeBy);
+    });
+    yield* Option.match(deadline, {
+      onNone: () => execution,
+      onSome: (at) => execution.pipe(Effect.timeoutOption(Math.max(0, at - started)), Effect.flatMap(Option.match({
+        onSome: () => Effect.void,
+        onNone: () => Clock.currentTimeMillis.pipe(Effect.flatMap((now) => Effect.logWarning(`background task ${taskId} of ${parent.id} was cut by the runner's deadline after ${now - started} ms`)))
+      })))
+    });
+  }).pipe(Effect.catchCause((cause) => Effect.logWarning(`background task ${taskId} of ${parent.id} stopped`, cause)), Effect.withSpan("task.run", { attributes: { "task.id": taskId, "session.id": parent.id } })), start = (parent, input) => Effect.gen(function* () {
+    const view = yield* sessions.get(parent);
+    if (Option.isSome(view.header.parent))
+      return yield* Effect.fail(new TaskRefused({ session: parent.id, reason: "depth", message: "a background task cannot start another task" }));
+    const taskId = input.taskId ?? ConversationId.make(yield* Effect.sync(() => crypto.randomUUID()));
+    if ((yield* sessions.transact(parent, () => Effect.gen(function* () {
+      const tasks = yield* listOf(parent);
+      if (tasks.some((task) => task.taskId === taskId))
+        return { drafts: [], result: !1 };
+      const active = tasks.filter((task) => isActive(task.status)).length;
+      if (active >= config.maxRunning)
+        return yield* Effect.fail(new TaskRefused({
+          session: parent.id,
+          reason: "limit",
+          message: `${active} background tasks are already running; wait for one to finish`
+        }));
+      yield* sessions.fork(parent, { id: taskId, origin: "task", meta: { taskId, mode: input.mode }, inherit: input.mode === "fork" }).pipe(Effect.catchTag("SessionExists", () => Effect.void));
+      const data = yield* startedJson({ taskId, instructions: input.instructions, mode: input.mode, meta: input.meta ?? {} });
+      return { drafts: [{ kind: TASK_STARTED, data }], result: !0 };
+    })).pipe(Effect.catchTag("ReservedKind", reservedAsStorage))).result)
+      yield* runner.run(work(parent, taskId));
+    return yield* taskOf(parent, taskId).pipe(Effect.catchTag("TaskMissing", () => Effect.fail(new SessionLogError({ code: "tasks.lost", message: `task ${taskId} was started but is not in ${parent.id}` }))));
+  }), cancel = (parent, taskId) => Effect.gen(function* () {
+    const task = yield* taskOf(parent, taskId);
+    if (!isActive(task.status))
+      return !1;
+    const child = childOf(parent, task.child), decided = yield* sessions.transact(child, (view) => sessions.read(child, { kinds: OUTCOME_KINDS }).pipe(Effect.map((records) => isActive(endOf(view, records).status) ? { drafts: [{ kind: TASK_CANCELLED, data: { taskId } }], result: { cancelled: !0, open: Option.map(view.open, (open) => open.turn) } } : { drafts: [], result: { cancelled: !1, open: Option.none() } }))).pipe(Effect.catchTag("ReservedKind", reservedAsStorage));
+    if (!decided.result.cancelled)
+      return !1;
+    yield* Option.match(decided.result.open, { onNone: () => Effect.void, onSome: (turn) => sessions.cancel(child, turn).pipe(Effect.asVoid) });
+    yield* sessions.transact(parent, () => Effect.succeed({ drafts: [{ kind: TASK_CANCELLED, data: { taskId } }], result: void 0 })).pipe(Effect.catchTag("ReservedKind", reservedAsStorage));
+    return !0;
+  }), reconcile = (parent) => Effect.gen(function* () {
+    const tasks = yield* listOf(parent), delivered = yield* Effect.forEach(tasks.filter((task) => isFinished(task.status) && !task.delivered), (task) => deliverNotice(parent, task)), waiting = tasks.filter((task) => task.status === "pending");
+    yield* Effect.forEach(waiting, (task) => runner.run(work(parent, task.taskId)), { discard: !0 });
+    return { delivered: delivered.filter((done) => done.delivered).length, started: waiting.length };
+  });
+  return Tasks.of({ start, status: taskOf, list: listOf, cancel, reconcile });
+}));

package/dist/tasks.adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@xandreed/plugin-tasks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.0-next.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@xandreed/core": "0.8.0-next.0",
+    "effect": "4.0.0-rc.118"
+  },
+  "private": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "profiles",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "license": "MIT"
+}