@qilin-agent/agent 0.0.0-stage → 3.1.4

package/lib/types/archive-admission.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `turn` family of the Workspace registry's archive admission: whether a
+ * Session's own Agent is inside a turn, and its cancel when the Session is
+ * archived with its work. Installed by the registry's constructor, so it
+ * answers for every Agent the registry publishes.
+ *
+ * @module @qilin-agent/agent
+ */
+import type { Context } from '@qilin-agent/kylin';
+import type { SessionId } from '@qilin-agent/session';
+import type { Agent } from './types.ts';
+/**
+ * Answer `workspace/session-activity` with the `turn` family while the
+ * Session's Agent is running (a turn waiting for an approval or an answer
+ * included), and `workspace/session-stop` by cancelling that turn the way
+ * the user's own stop does — `agent.cancel({ kind: 'user' })`, but without
+ * the stop button's `keepInbox`, so queued input is discarded with a logged
+ * inbox splice instead of waking the archived Session later. Nothing is
+ * awaited to settlement. Both listeners live as long as `ctx`'s fiber.
+ * @param ctx - the registry's registration context.
+ * @param lookup - the registry's live-Agent lookup by Session id.
+ */
+export declare function installTurnArchiveAdmission(ctx: Context, lookup: (sessionId: SessionId) => Agent | undefined): void;
+//# sourceMappingURL=archive-admission.d.ts.map

package/lib/types/archive-admission.js

@@ -0,0 +1,35 @@
+/**
+ * The `turn` family of the Workspace registry's archive admission: whether a
+ * Session's own Agent is inside a turn, and its cancel when the Session is
+ * archived with its work. Installed by the registry's constructor, so it
+ * answers for every Agent the registry publishes.
+ *
+ * @module @qilin-agent/agent
+ */
+/**
+ * Answer `workspace/session-activity` with the `turn` family while the
+ * Session's Agent is running (a turn waiting for an approval or an answer
+ * included), and `workspace/session-stop` by cancelling that turn the way
+ * the user's own stop does — `agent.cancel({ kind: 'user' })`, but without
+ * the stop button's `keepInbox`, so queued input is discarded with a logged
+ * inbox splice instead of waking the archived Session later. Nothing is
+ * awaited to settlement. Both listeners live as long as `ctx`'s fiber.
+ * @param ctx - the registry's registration context.
+ * @param lookup - the registry's live-Agent lookup by Session id.
+ */
+export function installTurnArchiveAdmission(ctx, lookup) {
+    ctx.on('workspace/session-activity', async ({ sessionId }, next) => {
+        const running = lookup(sessionId)?.status === 'running';
+        const rest = await next();
+        if (!running)
+            return rest;
+        const own = { kind: 'turn' };
+        return [own, ...rest];
+    });
+    ctx.on('workspace/session-stop', ({ sessionId }) => {
+        const agent = lookup(sessionId);
+        if (agent?.status === 'running')
+            agent.cancel({ kind: 'user' });
+    });
+}
+//# sourceMappingURL=archive-admission.js.map

package/lib/types/consumed-work.d.ts

@@ -0,0 +1,39 @@
+/**
+ * How one agent log accounts for the work it consumed.
+ *
+ * The turn and step vocabulary alone cannot answer this. A turn that stops
+ * before its first step leaves a `turn/end` shaped exactly like the balanced
+ * no-op turns a rejection or an empty claim produces, so reading turns in
+ * isolation either credits cut-short work as finished or convicts every no-op.
+ * The missing fact is the inbox's own record: {@link Inbox} logs each mutation
+ * with `removedCount` and marks a cancellation `outcome: 'canceled'`, which
+ * separates a turn claiming its input from work being dropped unrun.
+ *
+ * @module @qilin-agent/agent/consumed-work
+ */
+import type { SessionEvent } from '@qilin-agent/session';
+/** How one agent log accounts for the work it consumed. */
+export interface ConsumedWork {
+    /**
+     * The latest closed turn that accounts for consumed work: one that entered a
+     * model step, or one that claimed inbox input and then failed, was stopped,
+     * or was rejected. Absent when no turn closed over any work.
+     */
+    readonly end?: SessionEvent<'turn/end'>;
+    /**
+     * Whether accepted work was cancelled out of the inbox, unrun, after that
+     * turn. This is the only account of input a cancellation took before any turn
+     * could open over it — no `turn/end` describes it.
+     */
+    readonly droppedUnrun: boolean;
+}
+/**
+ * Fold one agent log, or an owned suffix of one, into its account of consumed
+ * work. Single pass, and every input is the log itself: no caller has to sample
+ * live state before cancelling, so a cancellation issued by anyone — the owner's
+ * teardown, an ancestor's interrupt, an unloading plugin — reads the same.
+ * @param events - the log, or an owned suffix, to fold.
+ * @returns the accounting turn when one closed, and whether work was dropped unrun after it.
+ */
+export declare function foldConsumedWork(events: readonly SessionEvent[]): ConsumedWork;
+//# sourceMappingURL=consumed-work.d.ts.map

package/lib/types/consumed-work.js

@@ -0,0 +1,93 @@
+/**
+ * How one agent log accounts for the work it consumed.
+ *
+ * The turn and step vocabulary alone cannot answer this. A turn that stops
+ * before its first step leaves a `turn/end` shaped exactly like the balanced
+ * no-op turns a rejection or an empty claim produces, so reading turns in
+ * isolation either credits cut-short work as finished or convicts every no-op.
+ * The missing fact is the inbox's own record: {@link Inbox} logs each mutation
+ * with `removedCount` and marks a cancellation `outcome: 'canceled'`, which
+ * separates a turn claiming its input from work being dropped unrun.
+ *
+ * @module @qilin-agent/agent/consumed-work
+ */
+/**
+ * Whether a turn that consumed input but never reached a step ends in a way
+ * that accounts for that input. Only a `completed` end does not: it had
+ * nothing left to run once its claim was rewritten away. A `blocked` end is
+ * that input's ending too — the pre-step rejection that produced it discarded
+ * the claimed messages, so the work it took will never run.
+ * @param reason - the turn's recorded ending.
+ * @returns whether the ending accounts for the input the turn took.
+ */
+function accountsForClaim(reason) {
+    switch (reason.kind) {
+        case 'completed':
+            return false;
+        case 'blocked':
+        case 'aborted':
+        case 'interrupted':
+        case 'error':
+            return true;
+        /* v8 ignore next 5 -- unreachable: `max-tokens` requires a step and short-circuits
+         * before this call; `forked` exists only in constructor seed history, while production
+         * callers fold an operation-owned suffix. `TurnEndReasonMap` is merge-extensible, so a
+         * backend-added variant cannot be listed; an unnameable ending over consumed input must
+         * not read as success. */
+        default:
+            return true;
+    }
+}
+/**
+ * Fold one agent log, or an owned suffix of one, into its account of consumed
+ * work. Single pass, and every input is the log itself: no caller has to sample
+ * live state before cancelling, so a cancellation issued by anyone — the owner's
+ * teardown, an ancestor's interrupt, an unloading plugin — reads the same.
+ * @param events - the log, or an owned suffix, to fold.
+ * @returns the accounting turn when one closed, and whether work was dropped unrun after it.
+ */
+export function foldConsumedWork(events) {
+    const stepped = new Set();
+    const claimed = new Set();
+    let open;
+    let end;
+    let droppedUnrun = false;
+    for (const event of events) {
+        switch (event.type) {
+            case 'turn/start':
+                open = event.data.turn;
+                break;
+            case 'step/start':
+                stepped.add(event.data.turn);
+                break;
+            case 'agent/inbox/spliced': {
+                const { removedCount, outcome, inserted } = event.data;
+                if (removedCount === undefined)
+                    break;
+                // A replacement keeps the work pending under a new identity, so only a
+                // cancellation that leaves nothing behind drops it.
+                if (outcome === 'canceled')
+                    droppedUnrun ||= inserted.length === 0;
+                // Claims are the loop's own step-boundary reads, always inside a turn.
+                else if (open !== undefined)
+                    claimed.add(open);
+                break;
+            }
+            case 'turn/end': {
+                const { turn, reason } = event.data;
+                open = undefined;
+                if (stepped.delete(turn) || (claimed.delete(turn) && accountsForClaim(reason))) {
+                    end = event;
+                    // Anything dropped before this turn closed is what its own ending
+                    // reports; only a later drop is still unaccounted for.
+                    droppedUnrun = false;
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return { ...end === undefined ? {} : { end }, droppedUnrun };
+}
+//# sourceMappingURL=consumed-work.js.map

package/lib/types/dispatch.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Agent-scoped dispatch and prompt assembly helpers. The fused dispatcher
+ * {@link agentEvents} couples the agent subject to its scope carrier, so the
+ * scope key and the payload's `agent` cannot diverge; repeat dispatchers (the
+ * loop driver) build it once in the agent's constructor and reuse it.
+ * @module @qilin-agent/agent/dispatch
+ */
+import type { Context, Events } from '@qilin-agent/kylin';
+import type { Scoped } from '@qilin-agent/scope';
+import type { AssembleContext } from '@qilin-agent/system-prompt';
+import type { Agent } from './types.ts';
+/** Extract the parameter tuple from an event handler type (its `this` is not part of the tuple). */
+type Params<F> = F extends (...args: infer P) => unknown ? P : never;
+/** Extract the return type from an event handler type. */
+type Return<F> = F extends (...args: never[]) => infer R ? R : never;
+/**
+ * The event names whose subject is an agent: the handler's first parameter is
+ * a payload object carrying the `agent` subject AND the handler declares a
+ * `Scoped<Agent>` `this` (the scope-carrier contract). The `this` check keeps
+ * accidental payload-happens-to-carry-an-Agent events (or zero-arg events,
+ * whose parameter tuple would satisfy a bare rest-tuple check via callability)
+ * out of the fused-dispatch surface.
+ */
+export type AgentSubjectEvent = {
+    [K in keyof Events]: Events[K] extends (this: Scoped<Agent>, ...args: infer P) => unknown ? P extends [infer Payload, ...unknown[]] ? Payload extends {
+        agent: Agent;
+    } ? K : never : never : never;
+}[keyof Events];
+/** The full payload object of one agent-subject event. */
+type PayloadOf<K extends AgentSubjectEvent> = Params<Events[K]> extends [infer Payload, ...unknown[]] ? Payload : never;
+/** The event arguments AFTER the payload: the waterfall `next` when present. */
+type Tail<K extends AgentSubjectEvent> = Params<Events[K]> extends [unknown, ...infer R] ? R : never;
+/**
+ * The payload as emit-side callers pass it: the full payload minus the agent
+ * field, which the fused dispatcher injects so subject and scope key cannot
+ * diverge.
+ */
+type PayloadRest<K extends AgentSubjectEvent> = Omit<PayloadOf<K> & object, 'agent'>;
+/**
+ * The fused dispatcher {@link agentEvents} returns: each method dispatches the
+ * named agent-subject event with the agent's scope carrier as `thisArg` and
+ * the agent itself injected into the payload.
+ */
+export interface AgentEventDispatch {
+    /**
+     * Fire-and-forget notification in the agent's scope. Every listener is
+     * invoked; synchronous throws and returned-promise rejections are logged and
+     * contained per listener, so a notification cannot veto lifecycle progress
+     * or starve a later observer.
+     * @param name - the agent-subject event to emit.
+     * @param payload - the event's payload fields; `agent` is injected.
+     */
+    emit<K extends AgentSubjectEvent>(name: K, payload: PayloadRest<K>): void;
+    /**
+     * Awaited in-order dispatch (Cordis `serial`) in the agent's scope.
+     * @param name - the agent-subject event to dispatch.
+     * @param payload - the event's payload fields; `agent` is injected.
+     * @returns the serial chain's result (the first bail value, if any).
+     */
+    serial<K extends AgentSubjectEvent>(name: K, payload: PayloadRest<K>): Promise<Awaited<Return<Events[K]>>>;
+    /**
+     * Around-middleware dispatch (Cordis `waterfall`) in the agent's scope. The
+     * declared event parameters already end with the `next` callback, so `rest`
+     * is exactly the event's arguments after the payload — the final element
+     * being the innermost `next` (the default the listener chain wraps).
+     * @param name - the agent-subject event to dispatch.
+     * @param payload - the event's payload fields; `agent` is injected.
+     * @param rest - the event's arguments after the payload (the `next` callback).
+     * @returns the waterfall's composed result.
+     */
+    waterfall<K extends AgentSubjectEvent>(name: K, payload: PayloadRest<K>, ...rest: Tail<K>): Return<Events[K]>;
+}
+/**
+ * Build the fused scope carrier for one agent subject.
+ *
+ * The carrier is a stateless routing object. {@link agentEvents} accepts an
+ * existing carrier, so callers that dispatch repeatedly for the same agent
+ * (the loop driver) build it once in the agent's constructor and reuse it,
+ * keeping hot-path dispatches allocation-free.
+ * @param agent - the subject agent and scope key.
+ * @returns the carrier passed as the event dispatcher `this` value.
+ */
+export declare function agentCarrier(agent: Agent): Scoped<Agent>;
+/**
+ * Build a dispatcher that couples the agent subject to its scope carrier.
+ * @param ctx - the context to dispatch through (any context of the app).
+ * @param agent - the subject agent; also the scope-carrier key.
+ * @param carrier - the scope carrier to dispatch through; defaults to
+ * {@link agentCarrier} for the agent. Pass a constructor-built carrier to
+ * avoid rebuilding it for every dispatch.
+ * @returns the fused dispatcher.
+ */
+export declare function agentEvents(ctx: Context, agent: Agent, carrier?: Scoped<Agent>): AgentEventDispatch;
+/**
+ * Emit one contained agent notification without allocating a retained dispatcher.
+ * @param ctx - the context to dispatch through.
+ * @param agent - the subject agent and scope key.
+ * @param name - the agent-subject event to emit.
+ * @param payload - the event's payload fields; `agent` is injected.
+ */
+export declare function emitAgentEvent<K extends AgentSubjectEvent>(ctx: Context, agent: Agent, name: K, payload: PayloadRest<K>): void;
+/**
+ * Build the prompt assembly context with agent and scope set together, so
+ * agent-scoped prompt and tool contributions cannot be silently omitted.
+ * @param agent - the agent the assembly is for.
+ * @param signal - the current turn's explicit control signal, when assembly belongs to a turn.
+ * @returns the context to pass to `assemble()`.
+ */
+export declare function assembleContextFor(agent: Agent, signal?: AbortSignal): AssembleContext;
+export {};
+//# sourceMappingURL=dispatch.d.ts.map

package/lib/types/dispatch.js

@@ -0,0 +1,95 @@
+/**
+ * Agent-scoped dispatch and prompt assembly helpers. The fused dispatcher
+ * {@link agentEvents} couples the agent subject to its scope carrier, so the
+ * scope key and the payload's `agent` cannot diverge; repeat dispatchers (the
+ * loop driver) build it once in the agent's constructor and reuse it.
+ * @module @qilin-agent/agent/dispatch
+ */
+import { scopeTarget } from '@qilin-agent/scope';
+/**
+ * Build the fused scope carrier for one agent subject.
+ *
+ * The carrier is a stateless routing object. {@link agentEvents} accepts an
+ * existing carrier, so callers that dispatch repeatedly for the same agent
+ * (the loop driver) build it once in the agent's constructor and reuse it,
+ * keeping hot-path dispatches allocation-free.
+ * @param agent - the subject agent and scope key.
+ * @returns the carrier passed as the event dispatcher `this` value.
+ */
+export function agentCarrier(agent) {
+    return scopeTarget(agent, agent);
+}
+/**
+ * Build a dispatcher that couples the agent subject to its scope carrier.
+ * @param ctx - the context to dispatch through (any context of the app).
+ * @param agent - the subject agent; also the scope-carrier key.
+ * @param carrier - the scope carrier to dispatch through; defaults to
+ * {@link agentCarrier} for the agent. Pass a constructor-built carrier to
+ * avoid rebuilding it for every dispatch.
+ * @returns the fused dispatcher.
+ */
+export function agentEvents(ctx, agent, carrier = agentCarrier(agent)) {
+    // The ordinary dispatch methods forward through Cordis' variadic mixins. The
+    // fused (carrier, name, payload, ...rest) tuple is provably a valid argument
+    // list for the matching thisArg overload, but TypeScript cannot relate the
+    // generic Tail<K> spread back to that overload's conditional parameter
+    // tuple — hence one contained, shape-preserving cast per method.
+    const fused = (payload) => 
+    // The dispatcher owns the subject injection; callers pass PayloadRest, so
+    // the fused record is exactly the declared payload. The spread comes
+    // first, so a structurally acceptable payload that happens to carry an
+    // `agent` field can never override the injected subject.
+    ({ ...payload, agent });
+    return {
+        emit(name, payload) {
+            // Cordis emit invokes callbacks through Array.map: one synchronous throw
+            // starves later listeners, and returned promises are discarded. Agent
+            // notifications are non-vetoing, so resolve the same filtered callback
+            // set ourselves and contain both failure modes independently.
+            const args = [carrier, name, fused(payload)];
+            const callbacks = ctx.events.dispatch('emit', args);
+            for (const callback of callbacks) {
+                try {
+                    const returned = callback(...args);
+                    void Promise.resolve(returned).catch((error) => {
+                        ctx.logger.warn(`agent event "${name}" listener rejected: ${String(error)}`);
+                    });
+                }
+                catch (error) {
+                    ctx.logger.warn(`agent event "${name}" listener threw: ${String(error)}`);
+                }
+            }
+        },
+        async serial(name, payload) {
+            // oxlint-disable-next-line typescript/unbound-method -- the events mixin accessor returns a pre-bound function
+            const serial = ctx.serial;
+            return await serial(carrier, name, fused(payload));
+        },
+        waterfall(name, payload, ...rest) {
+            // oxlint-disable-next-line typescript/unbound-method -- the events mixin accessor returns a pre-bound function
+            const waterfall = ctx.waterfall;
+            return waterfall(carrier, name, fused(payload), ...rest);
+        },
+    };
+}
+/**
+ * Emit one contained agent notification without allocating a retained dispatcher.
+ * @param ctx - the context to dispatch through.
+ * @param agent - the subject agent and scope key.
+ * @param name - the agent-subject event to emit.
+ * @param payload - the event's payload fields; `agent` is injected.
+ */
+export function emitAgentEvent(ctx, agent, name, payload) {
+    agentEvents(ctx, agent).emit(name, payload);
+}
+/**
+ * Build the prompt assembly context with agent and scope set together, so
+ * agent-scoped prompt and tool contributions cannot be silently omitted.
+ * @param agent - the agent the assembly is for.
+ * @param signal - the current turn's explicit control signal, when assembly belongs to a turn.
+ * @returns the context to pass to `assemble()`.
+ */
+export function assembleContextFor(agent, signal) {
+    return { agent, scope: agent, ...signal === undefined ? {} : { signal } };
+}
+//# sourceMappingURL=dispatch.js.map