@xandreed/core 0.12.0 → 0.14.0

package/dist/turn/tool-registry.conformance.js

@@ -0,0 +1,206 @@
+import { Tool } from "effect/ai";
+import { Context, Effect, Layer, Option, Ref, Schema, Stream } from "effect";
+import { check, expect, freshId } from "../conformance.functions.js";
+import { Failure } from "../domain/failure.entity.js";
+import { defineCapability, defineSkill, defineTool } from "../harness/capability.entity.functions.js";
+import { HarnessError } from "../harness/plugin.entity.js";
+import { CurrentAgentStep, CurrentToolInvocation } from "../loop/stepContext.js";
+import { EntryId } from "../memory/memory-log.entity.js";
+import { openLogSession } from "../memory/memory-session.js";
+import { ActionPolicy } from "../ports/harness.port.js";
+import { ConversationMemory } from "../ports/memory.port.js";
+import { PermissionGrants } from "../ports/permission.port.js";
+import { RunContext } from "../ports/run-context.port.js";
+import { ToolRegistry } from "../ports/tool-registry.port.js";
+import { TurnMemory, TurnToolbox } from "../ports/turn-scope.port.js";
+import { turnStartedDraft } from "../session/session-event.entity.functions.js";
+import { TurnLive } from "./turn.adapter.js";
+import { publishToolProgress } from "./turn-event.entity.functions.js";
+import { UserMessage } from "./user-message.entity.js";
+const RUN = "conformance-run", Opener = Context.Reference("efferent/conformance/ToolRegistryOpener", { defaultValue: () => "none" }), Ping = Tool.make("kit_ping", {
+  description: "Answer pong, at most twice per turn.",
+  parameters: Schema.Struct({ n: Schema.Int }),
+  success: Schema.String,
+  failure: Failure,
+  failureMode: "return"
+}), Report = Tool.make("kit_report", {
+  description: "Report progress twice, then say which call this was.",
+  parameters: Schema.Struct({}),
+  success: Schema.String,
+  failure: Failure,
+  failureMode: "return"
+}), Vault = Tool.make("kit_vault", {
+  description: "Read the vault, with the kit.vault permission.",
+  parameters: Schema.Struct({ key: Schema.String }),
+  success: Schema.String,
+  failure: Failure,
+  failureMode: "return"
+}), Archive = Tool.make("kit_archive", {
+  description: "Archive a record, once its skill is loaded.",
+  parameters: Schema.Struct({ id: Schema.String }),
+  success: Schema.String,
+  failure: Failure,
+  failureMode: "return"
+}), TOOLS = [Ping.name, Report.name, Vault.name, Archive.name], SKILLS = ["kit.basics", "kit.vault", "kit.archiving"], capabilityOf = (ran) => {
+  const note = (tool) => Ref.update(ran, (all) => [...all, tool]);
+  return defineCapability({
+    id: "conformance.tools",
+    version: "1",
+    tools: [
+      defineTool({ tool: Ping, handler: ({ n }) => note(Ping.name).pipe(Effect.as(`pong ${n}`)), annotations: { maxCallsPerRun: Option.some(2) } }),
+      defineTool({
+        tool: Report,
+        handler: () => Effect.gen(function* () {
+          yield* note(Report.name);
+          const invocation = yield* Effect.service(CurrentToolInvocation), opener = yield* Effect.service(Opener);
+          yield* publishToolProgress("stdout", "working");
+          yield* publishToolProgress("status", "half way");
+          return `${Option.match(invocation, { onNone: () => "no invocation", onSome: (call) => `${call.invocationId}|${call.tool}|${call.step}` })}|${opener}`;
+        })
+      }),
+      defineTool({ tool: Vault, handler: ({ key }) => note(Vault.name).pipe(Effect.as(`secret ${key}`)), annotations: { permissions: ["kit.vault"] } }),
+      defineTool({ tool: Archive, handler: ({ id }) => note(Archive.name).pipe(Effect.as(`archived ${id}`)) })
+    ],
+    skills: [
+      defineSkill({ id: "kit.basics", summary: "Ping and report.", tools: [Ping.name, Report.name], always: !0 }),
+      defineSkill({ id: "kit.vault", summary: "Read the vault.", tools: [Vault.name], permissions: ["kit.vault"] }),
+      defineSkill({ id: "kit.archiving", summary: "Archive records.", tools: [Archive.name] })
+    ]
+  });
+}, policy = {
+  strategy: { id: "conformance", version: "1" },
+  render: { turnContext: "current", replies: !0, digests: !0, media: { mode: "none", maxImages: 0, maxChars: 0 } },
+  digestOnWrite: Option.none(),
+  maintain: () => Effect.succeed({ actions: [], digest: [] })
+}, memoryWriter = Effect.gen(function* () {
+  const session = yield* freshId, userMessage = new UserMessage({ text: "use the tools" }), draft = yield* turnStartedDraft(1, {
+    runId: RUN,
+    key: RUN,
+    origin: "user",
+    userMessage,
+    command: {},
+    claimed: [],
+    entry: EntryId.make(`${RUN}:0`),
+    at: 0
+  }).pipe(Effect.orDie), started = { session, seq: 1, turn: draft.turn, kind: draft.kind, at: 0, data: draft.data }, stored = yield* Ref.make([started]), append = (drafts) => Ref.update(stored, (all) => [...all, ...drafts.map((next, index) => ({
+    session,
+    seq: all.length + index + 1,
+    turn: Option.some(1),
+    kind: next.kind,
+    at: 0,
+    data: JSON.parse(JSON.stringify(next.data))
+  }))]);
+  return { writer: {
+    admitted: { session: { id: session, owner: "conformance" }, turn: 1, runId: RUN, key: RUN, origin: "user", userMessage, command: {}, claimed: [], meta: {} },
+    started,
+    history: () => Effect.succeed([]),
+    snapshot: (kinds, after) => Ref.get(stored).pipe(Effect.map((events) => events.filter((event) => (after === void 0 || event.seq > after) && (kinds.length === 0 || kinds.includes(event.kind))))),
+    append,
+    write: (op) => op,
+    transact: (decide) => decide([]).pipe(Effect.flatMap((decision) => append(decision.drafts).pipe(Effect.as({ result: decision.result, events: [] })))),
+    flush: Effect.void,
+    end: () => Effect.succeed({ pending: 0 }),
+    closed: Effect.never
+  }, stored: Ref.get(stored) };
+}), messageOf = (result) => typeof result === "object" && result !== null && ("message" in result) && typeof result.message === "string" ? result.message : "none";
+export const toolRegistryConformance = (make) => {
+  const inTurn = (setup, body) => Effect.scoped(Effect.gen(function* () {
+    const ran = yield* Ref.make([]), registry = yield* make([capabilityOf(ran)], { maxCallsPerRun: setup.maxCallsPerRun ?? 32 }), recorded = yield* memoryWriter, services = Layer.merge(Layer.succeed(ConversationMemory, ConversationMemory.of({ strategy: policy.strategy, open: ({ runId, log }) => openLogSession(log, policy, { runId }) })), Layer.succeed(ToolRegistry, registry));
+    return yield* Effect.gen(function* () {
+      const run = yield* RunContext, published = yield* Ref.make([]);
+      yield* run.events.subscribe((event) => event._tag.startsWith("tool.") || event._tag === "skills.activated" ? Option.some(event) : Option.none(), (event) => Ref.update(published, (all) => [...all, event]));
+      const memory = yield* TurnMemory;
+      yield* memory.persistMessage;
+      if (setup.vaultActive === !0)
+        yield* memory.session.record([{ _tag: "ToolsActivated", skills: ["kit.vault"], tools: [Vault.name], source: "host", decision: Option.none() }], 0);
+      const tools = yield* (yield* TurnToolbox).open.pipe(Effect.provideService(Opener, "the opener's"), (open) => Option.match(Option.fromNullishOr(setup.policy), { onNone: () => open, onSome: (denying) => open.pipe(Effect.provideService(ActionPolicy, denying)) }), (open) => Option.match(Option.fromNullishOr(setup.grants), {
+        onNone: () => open,
+        onSome: (grants) => open.pipe(Effect.provideService(PermissionGrants, PermissionGrants.of({ grants: Effect.succeed(new Set(grants)) })))
+      }));
+      yield* tools.select(run.userMessage);
+      const call = (name, params, step = 1) => Effect.gen(function* () {
+        const kit = yield* tools.toolkit.pipe(Effect.provide(tools.handlers)), last = (yield* Stream.runCollect(yield* kit.handle(name, params))).at(-1);
+        return { isFailure: last?.isFailure ?? !0, result: last?.result };
+      }).pipe(Effect.provideService(CurrentAgentStep, Option.some(step)), Effect.provideService(Opener, "the caller's"));
+      return yield* body({
+        catalog: registry.catalog,
+        tools,
+        call,
+        published: run.flush.pipe(Effect.orDie, Effect.andThen(Ref.get(published))),
+        stored: run.flush.pipe(Effect.orDie, Effect.andThen(recorded.stored)),
+        ran: Ref.get(ran)
+      });
+    }).pipe(Effect.provide(TurnLive({ turn: recorded.writer })), Effect.provide(services));
+  })), tags = (events) => events.map((event) => event._tag).join(), idOf = (event) => ("invocationId" in event) ? event.invocationId : "", refusal = (reason, id, calls, setup = {}) => check(`a call refused as ${reason} takes its invocation id first, publishes one tool.refused and no tool.started on the run's bus only, and never runs the handler`, id, () => inTurn(setup, (turn) => Effect.gen(function* () {
+    const refusedAt = calls.length - 1, [tool, input] = calls[refusedAt], results = yield* Effect.forEach(calls, ([name, params]) => turn.call(name, params)), events = yield* turn.published, refused = events.flatMap((event) => event._tag === "tool.refused" ? [event] : []);
+    yield* expect(id, refused.length === 1, `the calls published ${refused.length} tool.refused`);
+    const event = refused[0];
+    yield* expect(id, event.reason === reason && event.tool === tool && event.step === 1 && JSON.stringify(event.input) === JSON.stringify(input), `the refusal was published as ${event.reason} of ${event.tool} at step ${event.step} with input ${JSON.stringify(event.input)}`);
+    yield* expect(id, event.invocationId === `${RUN}:call:${refusedAt}`, `the refused call's id is ${event.invocationId}, not ${RUN}:call:${refusedAt} (ids are minted before the checks)`);
+    const outcome = results[refusedAt];
+    yield* expect(id, outcome.isFailure && messageOf(outcome.result) === event.message && event.message.length > 0, `the refused call returned ${JSON.stringify(outcome.result)} (failure: ${outcome.isFailure}), not the refusal's message "${event.message}"`);
+    const others = events.filter((other) => other._tag !== "tool.refused" && idOf(other) === event.invocationId);
+    yield* expect(id, others.length === 0, `the refused call also published ${tags(others)}`);
+    const ran = yield* turn.ran;
+    yield* expect(id, ran.length === refusedAt, `the handlers ran for ${ran.join() || "no call"}; only the ${refusedAt} calls before the refused one should have`);
+    const stored = (yield* turn.stored).filter((record) => record.kind === "tool.refused");
+    yield* expect(id, stored.length === 1 && stored[0].data.invocationId === event.invocationId && !("input" in stored[0].data), `the turn stored ${stored.length} tool.refused${stored.length > 0 && "input" in stored[0].data ? ", with the call's input" : ""} (a registry publishes on the run's bus and never writes the journal itself)`);
+  })));
+  return [
+    check("the catalog and a run's tools hold every tool and skill the capabilities define, with their permissions", "catalog", () => inTurn({}, (turn) => Effect.gen(function* () {
+      const recipes = turn.catalog.recipes.map((recipe) => recipe.id), listed = turn.catalog.tools.map((tool) => tool.id);
+      yield* expect("catalog", SKILLS.every((skill) => recipes.includes(skill)) && TOOLS.every((tool) => listed.includes(tool)), `the catalog lists the skills ${recipes.join()} and the tools ${listed.join()}`);
+      const vault = turn.catalog.tools.find((tool) => tool.id === Vault.name);
+      yield* expect("catalog", vault?.permissions.join() === "kit.vault", `the catalog gives ${Vault.name} the permissions [${vault?.permissions.join() ?? "of no entry"}]`);
+      const skills = turn.tools.skills.map((skill) => skill.id);
+      yield* expect("catalog", SKILLS.every((skill) => skills.includes(skill)), `the run's skills are ${skills.join()}`);
+      const toolkit = Object.keys(turn.tools.toolkit.tools);
+      yield* expect("catalog", TOOLS.every((tool) => toolkit.includes(tool)), `the run's toolkit holds ${toolkit.join()}`);
+    }))),
+    check("always-on skills are active, others only once activated; an unknown skill is refused and an ungranted one stays inactive; the active set only grows", "activation", () => inTurn({}, (turn) => Effect.gen(function* () {
+      const active = yield* turn.tools.active;
+      yield* expect("activation", active.includes(Ping.name) && active.includes(Report.name) && !active.includes(Archive.name) && !active.includes(Vault.name), `with only the always-on skill applied, the active tools are ${active.join()}`);
+      const returned = yield* turn.tools.activate(["kit.archiving"], "host"), grown = yield* turn.tools.active;
+      yield* expect("activation", returned.includes(Archive.name) && grown.includes(Archive.name) && active.every((tool) => grown.includes(tool)), `after activating kit.archiving the active tools are ${grown.join()} (activate returned ${returned.join()})`);
+      yield* turn.tools.activate(["kit.archiving"], "host");
+      const again = yield* turn.tools.active;
+      yield* expect("activation", again.join() === grown.join(), `activating kit.archiving again changed the active tools to ${again.join()}`);
+      const activated = (yield* turn.published).flatMap((event) => event._tag === "skills.activated" ? [event] : []);
+      yield* expect("activation", activated.filter((event) => event.skills.includes("kit.archiving")).length === 1 && activated.some((event) => event.tools.includes(Archive.name)), `kit.archiving's activation published ${activated.length} skills.activated`);
+      const unknown = yield* Effect.flip(turn.tools.activate(["kit.no-such-skill"], "host"));
+      yield* expect("activation", unknown.code === "skills.unknown", `activating an unknown skill failed with ${unknown.code}`);
+      yield* Effect.result(turn.tools.activate(["kit.vault"], "host"));
+      const after = yield* turn.tools.active;
+      yield* expect("activation", !after.includes(Vault.name) && grown.every((tool) => after.includes(tool)), `after asking for a skill whose permission is not granted the active tools are ${after.join()}`);
+    }))),
+    check("a handled call publishes tool.started, its progress and tool.completed under one invocation id, minted after a refused call's, which its handler sees, on the run's bus only", "invocation", () => inTurn({}, (turn) => Effect.gen(function* () {
+      yield* turn.call(Archive.name, { id: "r0" });
+      const outcome = yield* turn.call(Report.name, {}, 2), id = `${RUN}:call:1`;
+      yield* expect("invocation", !outcome.isFailure && outcome.result === `${id}|${Report.name}|2|the opener's`, `the handler saw ${JSON.stringify(outcome.result)}, not its call ${id}|${Report.name}|2 and the services where the tools were opened`);
+      const events = (yield* turn.published).filter((event) => event._tag.startsWith("tool."));
+      yield* expect("invocation", tags(events) === "tool.refused,tool.started,tool.progress,tool.progress,tool.completed", `the two calls published ${tags(events)}`);
+      const handled = events.slice(1);
+      yield* expect("invocation", idOf(events[0]) === `${RUN}:call:0` && handled.every((event) => idOf(event) === id && ("tool" in event) && event.tool === Report.name && ("step" in event) && event.step === 2), `the calls' events carry the ids ${events.map(idOf).join()}`);
+      const completed = events.at(-1);
+      yield* expect("invocation", completed?._tag === "tool.completed" && completed.ok, "the handled call did not complete ok");
+      const stored = (yield* turn.stored).map((event) => event.kind).filter((kind) => kind.startsWith("tool."));
+      yield* expect("invocation", stored.join() === "tool.refused,tool.started,tool.completed", `the turn stored ${stored.join()} (a registry publishes on the run's bus and never writes the journal itself)`);
+      const next = yield* turn.call(Ping.name, { n: 1 }), started = (yield* turn.published).filter((event) => event._tag === "tool.started").map(idOf);
+      yield* expect("invocation", !next.isFailure && started.join() === `${id},${RUN}:call:2`, `the next call took the id ${started.at(-1) ?? "none"}`);
+    }))),
+    check("the turn's PermissionGrants, read where the tools are opened, let a skill that needs them be activated and its tools run", "grants", () => inTurn({ grants: ["kit.vault"] }, (turn) => Effect.gen(function* () {
+      yield* turn.tools.activate(["kit.vault"], "host");
+      const active = yield* turn.tools.active;
+      yield* expect("grants", active.includes(Vault.name), `with kit.vault granted, activating its skill left the active tools ${active.join()}`);
+      const outcome = yield* turn.call(Vault.name, { key: "k" });
+      yield* expect("grants", !outcome.isFailure && outcome.result === "secret k", `the granted call returned ${JSON.stringify(outcome.result)}`);
+    }))),
+    refusal("inactive", "refused-inactive", [[Archive.name, { id: "r1" }]]),
+    refusal("forbidden", "refused-forbidden", [[Vault.name, { key: "k" }]], { vaultActive: !0 }),
+    refusal("denied", "refused-denied", [[Ping.name, { n: 1 }]], {
+      policy: ActionPolicy.of({ authorize: (tool) => tool === Ping.name ? Effect.fail(new HarnessError({ code: "conformance.denied", message: "pings are closed today" })) : Effect.void })
+    }),
+    refusal("call-limit", "refused-call-limit", [[Ping.name, { n: 1 }], [Ping.name, { n: 2 }]], { maxCallsPerRun: 1 }),
+    refusal("tool-call-limit", "refused-tool-call-limit", [[Ping.name, { n: 1 }], [Ping.name, { n: 2 }], [Ping.name, { n: 3 }]])
+  ];
+};

package/dist/turn/turn-bus.js

@@ -1,5 +1,6 @@
 import { Cause, Context, Deferred, Effect, Fiber, Option, Queue, Ref } from "effect";
 import { HarnessError } from "../harness/plugin.entity.js";
+import { CurrentTraceContent, replayableContext } from "../loop/traceContent.js";
 const failureOf = (cause) => Option.getOrElse(Cause.findErrorOption(cause), () => {
   const defect = Cause.squash(cause);
   return defect instanceof HarnessError ? defect : new HarnessError({ code: "events.background", message: Cause.pretty(cause).slice(0, 300) });
@@ -20,7 +21,7 @@ export const makeTurnEvents = (options) => Effect.gen(function* () {
       }
       if (Option.isSome(failure))
         return;
-      yield* handle(item.event).pipe(Effect.provideService(depth, item.depth), Effect.catchCause((cause) => Ref.set(failed, Option.some(failureOf(cause)))));
+      yield* handle(item.event).pipe(Effect.provideService(depth, item.depth), Effect.provideService(CurrentTraceContent, item.traceContent), Effect.catchCause((cause) => Ref.set(failed, Option.some(failureOf(cause)))));
     })));
     yield* Effect.forkScoped(Effect.forever(take));
     const deliver = (event) => Effect.gen(function* () {
@@ -28,11 +29,11 @@ export const makeTurnEvents = (options) => Effect.gen(function* () {
       if (Option.isSome(failure))
         return yield* Effect.fail(failure.value);
       yield* Ref.update(queued, (value) => value + 1);
-      yield* Queue.offer(queue, { _tag: "Event", event, depth: yield* Effect.service(depth) });
+      yield* Queue.offer(queue, { _tag: "Event", event, depth: yield* Effect.service(depth), traceContent: yield* Effect.service(CurrentTraceContent) });
     }), drain = Deferred.make().pipe(Effect.flatMap((done) => Queue.offer(queue, { _tag: "Marker", done }).pipe(Effect.andThen(Deferred.await(done)))));
     return { deliver, drain };
   }), subscribe = (select, handle, subscribeOptions) => Effect.gen(function* () {
-    const context = yield* Effect.context(), id = yield* Ref.getAndUpdate(nextId, (value) => value + 1), handled = (selected) => handle(selected).pipe(Effect.provide(context)), lane = (subscribeOptions?.mode ?? "inline") === "background" ? yield* background(handled, subscribeOptions?.capacity ?? defaultCapacity) : { deliver: handled, drain: Effect.void }, deliver = (event) => Option.match(select(event), {
+    const context = replayableContext(yield* Effect.context()), id = yield* Ref.getAndUpdate(nextId, (value) => value + 1), handled = (selected) => handle(selected).pipe(Effect.provide(context)), lane = (subscribeOptions?.mode ?? "inline") === "background" ? yield* background(handled, subscribeOptions?.capacity ?? defaultCapacity) : { deliver: handled, drain: Effect.void }, deliver = (event) => Option.match(select(event), {
       onNone: () => Effect.void,
       onSome: lane.deliver
     });

package/dist/turn/turn-event.entity.d.ts

@@ -9,18 +9,22 @@ export declare const CompletionVerdict: Schema.Struct<{
     readonly facts: Schema.$Record<Schema.String, Schema.Unknown>;
 }>;
 export type CompletionVerdict = typeof CompletionVerdict.Type;
-export declare const TurnStartedEvent: Schema.TaggedStruct<"turn.started", {
+export declare const TurnStartedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"turn.started">;
     readonly runId: Schema.String;
     readonly turn: Schema.Int;
     readonly userMessage: typeof UserMessage;
+    readonly meta: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly resumes: Schema.optionalKey<Schema.Int>;
 }>;
-export declare const StepStartedEvent: Schema.TaggedStruct<"step.started", {
+export declare const StepStartedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"step.started">;
     readonly step: Schema.Int;
-    /** Step zero of a host-planned batch: no provider call. */
     readonly planned: Schema.Boolean;
     readonly activeTools: Schema.$Array<Schema.String>;
 }>;
-export declare const ToolStartedEvent: Schema.TaggedStruct<"tool.started", {
+export declare const ToolStartedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"tool.started">;
     readonly step: Schema.Int;
     readonly invocationId: Schema.String;
     readonly tool: Schema.String;
@@ -28,20 +32,45 @@ export declare const ToolStartedEvent: Schema.TaggedStruct<"tool.started", {
     readonly labels: Schema.$Record<Schema.String, Schema.String>;
     readonly stage: Schema.OptionFromNullOr<Schema.String>;
 }>;
-export declare const ToolCompletedEvent: Schema.TaggedStruct<"tool.completed", {
+/** Why the tool registry refused a call before its handler ran. */
+export declare const ToolRefusalReason: Schema.Literals<readonly ["inactive", "forbidden", "denied", "call-limit", "tool-call-limit"]>;
+export type ToolRefusalReason = typeof ToolRefusalReason.Type;
+export declare const ToolRefusedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"tool.refused">;
+    readonly step: Schema.Int;
+    readonly invocationId: Schema.String;
+    readonly tool: Schema.String;
+    readonly input: Schema.Unknown;
+    readonly reason: Schema.Literals<readonly ["inactive", "forbidden", "denied", "call-limit", "tool-call-limit"]>;
+    readonly message: Schema.String;
+}>;
+export declare const ToolCompletedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"tool.completed">;
     readonly step: Schema.Int;
     readonly invocationId: Schema.String;
     readonly tool: Schema.String;
     readonly input: Schema.Unknown;
     readonly ok: Schema.Boolean;
-    /** The decoded value the handler returned (or failed with). Not journaled. */
     readonly result: Schema.Unknown;
-    /** The wire form of `result`, as the model receives it. */
     readonly encoded: Schema.Unknown;
     readonly durationMs: Schema.Number;
     readonly labels: Schema.$Record<Schema.String, Schema.String>;
     readonly stage: Schema.OptionFromNullOr<Schema.String>;
 }>;
+/**
+ * What a running tool reports before it completes: a command's output as it
+ * arrives (`stdout`, `stderr`), or a step of a long job (`status`).
+ * Transient: shown live, never journaled; `tool.completed` carries the
+ * result. A handler publishes it with `publishToolProgress`.
+ */
+export declare const ToolProgressEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"tool.progress">;
+    readonly step: Schema.Int;
+    readonly invocationId: Schema.String;
+    readonly tool: Schema.String;
+    readonly channel: Schema.Literals<readonly ["stdout", "stderr", "status"]>;
+    readonly text: Schema.String;
+}>;
 export declare const StepResult: Schema.Struct<{
     readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
     readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
@@ -49,10 +78,10 @@ export declare const StepResult: Schema.Struct<{
     readonly ok: Schema.Boolean;
 }>;
 export type StepResult = typeof StepResult.Type;
-export declare const StepEndedEvent: Schema.TaggedStruct<"step.ended", {
+export declare const StepEndedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"step.ended">;
     readonly step: Schema.Int;
     readonly status: Schema.Literals<readonly ["completed", "failed", "cancelled"]>;
-    /** The step's recorded tool results, in log order. */
     readonly results: Schema.$Array<Schema.Struct<{
         readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
         readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
@@ -60,7 +89,8 @@ export declare const StepEndedEvent: Schema.TaggedStruct<"step.ended", {
         readonly ok: Schema.Boolean;
     }>>;
 }>;
-export declare const CompletionEvaluatedEvent: Schema.TaggedStruct<"completion.evaluated", {
+export declare const CompletionEvaluatedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"completion.evaluated">;
     readonly step: Schema.Int;
     readonly verdict: Schema.Struct<{
         readonly complete: Schema.Boolean;
@@ -70,12 +100,14 @@ export declare const CompletionEvaluatedEvent: Schema.TaggedStruct<"completion.e
         readonly facts: Schema.$Record<Schema.String, Schema.Unknown>;
     }>;
 }>;
-export declare const SkillsActivatedEvent: Schema.TaggedStruct<"skills.activated", {
+export declare const SkillsActivatedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"skills.activated">;
     readonly skills: Schema.$Array<Schema.String>;
     readonly tools: Schema.$Array<Schema.String>;
     readonly source: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
 }>;
-export declare const ContextBuiltEvent: Schema.TaggedStruct<"context.built", {
+export declare const ContextBuiltEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"context.built">;
     readonly step: Schema.Int;
     readonly turn: Schema.Int;
     readonly strategy: Schema.String;
@@ -84,10 +116,12 @@ export declare const ContextBuiltEvent: Schema.TaggedStruct<"context.built", {
     readonly systemFingerprint: Schema.String;
     readonly estimatedTokens: Schema.Int;
     readonly reservedTokens: Schema.Int;
+    readonly budgetTokens: Schema.Int;
     readonly compactions: Schema.Int;
     readonly activeTools: Schema.$Array<Schema.String>;
 }>;
-export declare const DecisionRecordedEvent: Schema.TaggedStruct<"decision.recorded", {
+export declare const DecisionRecordedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"decision.recorded">;
     readonly record: Schema.Struct<{
         readonly version: Schema.Literal<1>;
         readonly id: Schema.brand<Schema.Trimmed, "DecisionId">;
@@ -107,7 +141,8 @@ export declare const DecisionRecordedEvent: Schema.TaggedStruct<"decision.record
         readonly probabilities: Schema.OptionFromNullOr<Schema.$Record<Schema.String, Schema.Number>>;
     }>;
 }>;
-export declare const AssistantMessageEvent: Schema.TaggedStruct<"assistant.message", {
+export declare const AssistantMessageEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"assistant.message">;
     readonly step: Schema.Int;
     readonly text: Schema.String;
     readonly reasoning: Schema.String;
@@ -122,66 +157,103 @@ export declare const AssistantMessageEvent: Schema.TaggedStruct<"assistant.messa
         readonly outputTokens: Schema.Number;
         readonly totalTokens: Schema.Number;
         readonly cacheReadTokens: Schema.Number;
+        readonly cacheWriteTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        readonly reasoningTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
     }>;
 }>;
 /** A streamed increment — transient: never journaled, restated by assistant.message. */
-export declare const AssistantDeltaEvent: Schema.TaggedStruct<"assistant.delta", {
+export declare const AssistantDeltaEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"assistant.delta">;
     readonly step: Schema.Int;
     readonly channel: Schema.Literals<readonly ["text", "reasoning", "tool-params"]>;
     readonly id: Schema.String;
     readonly delta: Schema.String;
 }>;
-export declare const TurnEndedEvent: Schema.TaggedStruct<"turn.ended", {
+export declare const StreamFallbackEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"stream.fallback">;
+    readonly step: Schema.Int;
+    readonly message: Schema.String;
+}>;
+export declare const TurnEndedEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"turn.ended">;
     readonly runId: Schema.String;
     readonly turn: Schema.Int;
     readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed"]>;
     readonly reply: Schema.OptionFromNullOr<Schema.String>;
+    readonly usage: Schema.Struct<{
+        readonly inputTokens: Schema.Number;
+        readonly outputTokens: Schema.Number;
+        readonly totalTokens: Schema.Number;
+        readonly cacheReadTokens: Schema.Number;
+        readonly cacheWriteTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        readonly reasoningTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+    }>;
 }>;
 /** An application's own event (see `defineHostEvent`); `name` is the host's namespace. */
-export declare const HostEvent: Schema.TaggedStruct<"host", {
+export declare const HostEvent: Schema.Struct<{
+    readonly _tag: Schema.tag<"host">;
     readonly name: Schema.Trimmed;
     readonly data: Schema.$Record<Schema.String, Schema.Unknown>;
 }>;
-export declare const TurnEvent: Schema.Union<readonly [Schema.TaggedStruct<"turn.started", {
+export declare const TurnEvent: Schema.Union<readonly [Schema.Struct<{
+    readonly _tag: Schema.tag<"turn.started">;
     readonly runId: Schema.String;
     readonly turn: Schema.Int;
     readonly userMessage: typeof UserMessage;
-}>, Schema.TaggedStruct<"step.started", {
+    readonly meta: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly resumes: Schema.optionalKey<Schema.Int>;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"step.started">;
     readonly step: Schema.Int;
-    /** Step zero of a host-planned batch: no provider call. */
     readonly planned: Schema.Boolean;
     readonly activeTools: Schema.$Array<Schema.String>;
-}>, Schema.TaggedStruct<"tool.started", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"tool.started">;
     readonly step: Schema.Int;
     readonly invocationId: Schema.String;
     readonly tool: Schema.String;
     readonly input: Schema.Unknown;
     readonly labels: Schema.$Record<Schema.String, Schema.String>;
     readonly stage: Schema.OptionFromNullOr<Schema.String>;
-}>, Schema.TaggedStruct<"tool.completed", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"tool.refused">;
+    readonly step: Schema.Int;
+    readonly invocationId: Schema.String;
+    readonly tool: Schema.String;
+    readonly input: Schema.Unknown;
+    readonly reason: Schema.Literals<readonly ["inactive", "forbidden", "denied", "call-limit", "tool-call-limit"]>;
+    readonly message: Schema.String;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"tool.progress">;
+    readonly step: Schema.Int;
+    readonly invocationId: Schema.String;
+    readonly tool: Schema.String;
+    readonly channel: Schema.Literals<readonly ["stdout", "stderr", "status"]>;
+    readonly text: Schema.String;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"tool.completed">;
     readonly step: Schema.Int;
     readonly invocationId: Schema.String;
     readonly tool: Schema.String;
     readonly input: Schema.Unknown;
     readonly ok: Schema.Boolean;
-    /** The decoded value the handler returned (or failed with). Not journaled. */
     readonly result: Schema.Unknown;
-    /** The wire form of `result`, as the model receives it. */
     readonly encoded: Schema.Unknown;
     readonly durationMs: Schema.Number;
     readonly labels: Schema.$Record<Schema.String, Schema.String>;
     readonly stage: Schema.OptionFromNullOr<Schema.String>;
-}>, Schema.TaggedStruct<"step.ended", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"step.ended">;
     readonly step: Schema.Int;
     readonly status: Schema.Literals<readonly ["completed", "failed", "cancelled"]>;
-    /** The step's recorded tool results, in log order. */
     readonly results: Schema.$Array<Schema.Struct<{
         readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
         readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
         readonly tool: Schema.String;
         readonly ok: Schema.Boolean;
     }>>;
-}>, Schema.TaggedStruct<"completion.evaluated", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"completion.evaluated">;
     readonly step: Schema.Int;
     readonly verdict: Schema.Struct<{
         readonly complete: Schema.Boolean;
@@ -190,11 +262,13 @@ export declare const TurnEvent: Schema.Union<readonly [Schema.TaggedStruct<"turn
         /** Host facts behind the verdict, journaled with it. */
         readonly facts: Schema.$Record<Schema.String, Schema.Unknown>;
     }>;
-}>, Schema.TaggedStruct<"skills.activated", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"skills.activated">;
     readonly skills: Schema.$Array<Schema.String>;
     readonly tools: Schema.$Array<Schema.String>;
     readonly source: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
-}>, Schema.TaggedStruct<"context.built", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"context.built">;
     readonly step: Schema.Int;
     readonly turn: Schema.Int;
     readonly strategy: Schema.String;
@@ -203,9 +277,11 @@ export declare const TurnEvent: Schema.Union<readonly [Schema.TaggedStruct<"turn
     readonly systemFingerprint: Schema.String;
     readonly estimatedTokens: Schema.Int;
     readonly reservedTokens: Schema.Int;
+    readonly budgetTokens: Schema.Int;
     readonly compactions: Schema.Int;
     readonly activeTools: Schema.$Array<Schema.String>;
-}>, Schema.TaggedStruct<"decision.recorded", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"decision.recorded">;
     readonly record: Schema.Struct<{
         readonly version: Schema.Literal<1>;
         readonly id: Schema.brand<Schema.Trimmed, "DecisionId">;
@@ -224,7 +300,8 @@ export declare const TurnEvent: Schema.Union<readonly [Schema.TaggedStruct<"turn
         readonly applied: Schema.OptionFromNullOr<Schema.String>;
         readonly probabilities: Schema.OptionFromNullOr<Schema.$Record<Schema.String, Schema.Number>>;
     }>;
-}>, Schema.TaggedStruct<"assistant.message", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"assistant.message">;
     readonly step: Schema.Int;
     readonly text: Schema.String;
     readonly reasoning: Schema.String;
@@ -239,18 +316,35 @@ export declare const TurnEvent: Schema.Union<readonly [Schema.TaggedStruct<"turn
         readonly outputTokens: Schema.Number;
         readonly totalTokens: Schema.Number;
         readonly cacheReadTokens: Schema.Number;
+        readonly cacheWriteTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        readonly reasoningTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
     }>;
-}>, Schema.TaggedStruct<"assistant.delta", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"assistant.delta">;
     readonly step: Schema.Int;
     readonly channel: Schema.Literals<readonly ["text", "reasoning", "tool-params"]>;
     readonly id: Schema.String;
     readonly delta: Schema.String;
-}>, Schema.TaggedStruct<"turn.ended", {
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"stream.fallback">;
+    readonly step: Schema.Int;
+    readonly message: Schema.String;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"turn.ended">;
     readonly runId: Schema.String;
     readonly turn: Schema.Int;
     readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed"]>;
     readonly reply: Schema.OptionFromNullOr<Schema.String>;
-}>, Schema.TaggedStruct<"host", {
+    readonly usage: Schema.Struct<{
+        readonly inputTokens: Schema.Number;
+        readonly outputTokens: Schema.Number;
+        readonly totalTokens: Schema.Number;
+        readonly cacheReadTokens: Schema.Number;
+        readonly cacheWriteTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        readonly reasoningTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+    }>;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"host">;
     readonly name: Schema.Trimmed;
     readonly data: Schema.$Record<Schema.String, Schema.Unknown>;
 }>]>;
@@ -261,3 +355,9 @@ export type TurnEventOf<Name extends TurnEventName> = Extract<TurnEvent, {
 }>;
 /** Events that exist only for live rendering and are never journaled. */
 export declare const TransientTurnEvents: ReadonlyArray<TurnEventName>;
+/**
+ * Every bus event's name, in the union's order. All of them are reserved
+ * (`RESERVED_KINDS`): a host event may not take one, whether the journal
+ * stores the bus event under that name or not.
+ */
+export declare const TURN_EVENT_NAMES: ReadonlyArray<TurnEventName>;

package/dist/turn/turn-event.entity.functions.d.ts

@@ -33,3 +33,14 @@ export declare const defineHostEvent: <A, I extends Readonly<Record<string, unkn
     publish: (events: TurnEventsService, data: A) => Effect.Effect<void, HarnessError, never>;
     on: <R>(handle: (data: A) => Effect.Effect<void, HarnessError, R>, options?: SubscribeOptions) => Subscription<R>;
 };
+/**
+ * Report progress from inside a tool handler: publishes a transient
+ * `tool.progress` with the call's step, invocation id and tool name (from
+ * `CurrentToolInvocation`) on the run's bus. `channel` is `stdout` or
+ * `stderr` for a command's output as it arrives, `status` for anything else.
+ * Outside a tool call, or without a `RunContext`, it does nothing. As for
+ * `tool.started`, a subscriber failure fails the turn: the handler stops
+ * there, and the tool registry fails the turn after `tool.completed`
+ * instead of handing the failure to the model as the tool's result.
+ */
+export declare const publishToolProgress: (channel: TurnEventOf<"tool.progress">["channel"], text: string) => Effect.Effect<void>;

package/dist/turn/turn-event.entity.functions.js

@@ -1,5 +1,7 @@
 import { Effect, Option, Schema } from "effect";
 import { HarnessError } from "../harness/plugin.entity.js";
+import { CurrentToolInvocation } from "../loop/stepContext.js";
+import { RunContext } from "../ports/run-context.port.js";
 const isNamed = (name) => (event) => event._tag === name;
 export const onEvent = (name, handle, options) => (events) => events.subscribe((event) => Option.liftPredicate(event, isNamed(name)), handle, options), onTool = (tool, handle, options) => {
   const isInput = Schema.is(tool.parametersSchema), isResult = Schema.is(tool.successSchema);
@@ -18,4 +20,10 @@ export const onEvent = (name, handle, options) => (events) => events.subscribe((
     publish: (events, data) => make(data).pipe(Effect.flatMap(events.publish)),
     on: (handle, options) => (events) => events.subscribe(select, handle, options)
   };
-};
+}, publishToolProgress = (channel, text) => Effect.gen(function* () {
+  const invocation = yield* Effect.service(CurrentToolInvocation), run = yield* Effect.serviceOption(RunContext);
+  if (Option.isNone(invocation) || Option.isNone(run))
+    return;
+  const { step, invocationId, tool } = invocation.value;
+  yield* run.value.events.publish({ _tag: "tool.progress", step, invocationId, tool, channel, text }).pipe(Effect.orDie);
+});