@adonis-agora/agent 0.31.0 → 0.33.1

package/dist/src/runners/inline-agent-runner.d.ts

@@ -1,13 +1,20 @@
 import type { AgentDepsFactory } from '../agent-deps-factory.js';
+import { type HumanReply } from '../elicitation.js';
 import type { AgentRunner } from '../spi/agent-runner.js';
 import type { AgentStore } from '../spi/agent-store.js';
-import type { AgentRunInput, Decision } from '../types.js';
+import type { AgentRunInput } from '../types.js';
 /**
- * Runs the agent turn in-process — the default runner (`durable: false`). HITL approval resolves a
- * pending promise keyed run-namespaced by `${runId}:${toolCallId}`, so one run's decision can never
- * satisfy another's pending action. Sub-agent delegation runs a nested loop; a nested sub-agent has
- * no human to prompt, so its action tools are auto-declined rather than hang. Single-replica only —
- * durable is the scaled path (deferred).
+ * Runs the agent turn in-process — the default runner (`durable: false`). A HITL wait resolves a
+ * pending promise keyed run-namespaced by `${runId}:${toolCallId}`, so one run's reply can never
+ * satisfy another's pending action.
+ *
+ * Sub-agent delegation runs a nested loop on a transient sub-thread, and that nested run parks on a
+ * human exactly as a top-level one does — under its OWN runId, which is what makes it answerable:
+ * the pending row it writes carries that runId, and its frames are forwarded into the top-level
+ * ancestor's stream (the only stream anyone subscribed to) carrying it too. The mirror of the
+ * durable runner's `sinkRunId`.
+ *
+ * Single-replica only — durable is the scaled path (deferred).
  */
 export declare class InlineAgentRunner implements AgentRunner {
     private readonly factory;
@@ -17,9 +24,28 @@ export declare class InlineAgentRunner implements AgentRunner {
     start(input: AgentRunInput): Promise<{
         runId: string;
     }>;
-    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
+    /**
+     * Deliver a human's reply to whichever wait this run is parked on.
+     *
+     * An approval wait takes a {@link Decision} only. Answers addressed there are refused rather than
+     * delivered: `approved` is absent on them, and the tool-call row would record a rejection the
+     * person never made. The refusal leaves the wait intact, so the approval is still there to make.
+     *
+     * The other direction IS delivered — a question set parks as a `pending_approval` action, so an
+     * operator pressing Approve on it is expected, and the loop reads that as "confirmed the
+     * pre-picked answers".
+     */
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
     cancel(runId: string): Promise<void>;
     private topLevelHooks;
+    /**
+     * The two waits a run parks on, keyed by the run that is parked. Identical for a top-level run and
+     * for a delegated one: `signal(runId, …)` finds either, because the pending map belongs to the
+     * runner rather than to a run.
+     */
+    private humanHooks;
+    /** Hold a run at `key` until a human's reply arrives through {@link InlineAgentRunner.signal}. */
+    private park;
     /** Delegate to another agent as a nested in-process run (a transient sub-thread). */
     private runNested;
 }

package/dist/src/runners/inline-agent-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inline-agent-runner.d.ts","sourceRoot":"","sources":["../../../src/runners/inline-agent-runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAS,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAElE;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IAIjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmD;IAE3E,YACmB,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,UAAU,EAChC;IAEE,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CA6B5D;IAEK,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjF;IAEK,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzC;IAED,OAAO,CAAC,aAAa;IAerB,qFAAqF;YACvE,SAAS;CAmCxB"}
+{"version":3,"file":"inline-agent-runner.d.ts","sourceRoot":"","sources":["../../../src/runners/inline-agent-runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,OAAO,EAEL,KAAK,UAAU,EAGhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,KAAK,EAAS,aAAa,EAAY,MAAM,aAAa,CAAC;AAYlE;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IAIjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IAEzD,YACmB,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,UAAU,EAChC;IAEE,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAyC5D;IAED;;;;;;;;;;OAUG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;IAEK,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzC;IAED,OAAO,CAAC,aAAa;IAkCrB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAWlB,kGAAkG;IAClG,OAAO,CAAC,IAAI;IAMZ,qFAAqF;YACvE,SAAS;CAgExB"}

package/dist/src/runners/inline-agent-runner.js

@@ -1,12 +1,20 @@
 import { utcDay } from '../agent-deps.js';
-import { runAgentLoop } from '../agent-loop.js';
+import { runAgentLoop, settleAll } from '../agent-loop.js';
 import { spannedAgent } from '../diagnostics.js';
+import { HumanReplyMismatchError, isHumanDecision, } from '../elicitation.js';
+import { childSinkWriter } from '../spi/token-stream-sink.js';
 /**
- * Runs the agent turn in-process — the default runner (`durable: false`). HITL approval resolves a
- * pending promise keyed run-namespaced by `${runId}:${toolCallId}`, so one run's decision can never
- * satisfy another's pending action. Sub-agent delegation runs a nested loop; a nested sub-agent has
- * no human to prompt, so its action tools are auto-declined rather than hang. Single-replica only —
- * durable is the scaled path (deferred).
+ * Runs the agent turn in-process — the default runner (`durable: false`). A HITL wait resolves a
+ * pending promise keyed run-namespaced by `${runId}:${toolCallId}`, so one run's reply can never
+ * satisfy another's pending action.
+ *
+ * Sub-agent delegation runs a nested loop on a transient sub-thread, and that nested run parks on a
+ * human exactly as a top-level one does — under its OWN runId, which is what makes it answerable:
+ * the pending row it writes carries that runId, and its frames are forwarded into the top-level
+ * ancestor's stream (the only stream anyone subscribed to) carrying it too. The mirror of the
+ * durable runner's `sinkRunId`.
+ *
+ * Single-replica only — durable is the scaled path (deferred).
  */
 export class InlineAgentRunner {
     factory;
@@ -20,7 +28,19 @@ export class InlineAgentRunner {
         const runId = crypto.randomUUID();
         const day = input.day ?? utcDay();
         const deps = this.factory.forAgent(input.agentName);
-        const hooks = this.topLevelHooks(runId, deps, input.actor, day);
+        const hooks = this.topLevelHooks({
+            runId,
+            deps,
+            actor: input.actor,
+            day,
+            // The chain this run sits on with its OWN agent appended — what lets a child recognise a
+            // delegation back to an agent the chain has already passed through.
+            chainBelow: [
+                ...(input.delegationPath ?? []),
+                ...(input.agentName !== undefined ? [input.agentName] : []),
+            ],
+            depth: input.delegationDepth ?? 0,
+        });
         // The root turn span — the trace's root, correlated to every child step span by traceId = runId.
         // Emitted by the runner (not the shared loop) because the inline runner executes the loop exactly
         // once; the durable runner's body replays, so it roots its trace by traceId instead. Zero-cost
@@ -38,13 +58,28 @@ export class InlineAgentRunner {
         });
         return { runId };
     }
-    async signal(runId, toolCallId, decision) {
+    /**
+     * Deliver a human's reply to whichever wait this run is parked on.
+     *
+     * An approval wait takes a {@link Decision} only. Answers addressed there are refused rather than
+     * delivered: `approved` is absent on them, and the tool-call row would record a rejection the
+     * person never made. The refusal leaves the wait intact, so the approval is still there to make.
+     *
+     * The other direction IS delivered — a question set parks as a `pending_approval` action, so an
+     * operator pressing Approve on it is expected, and the loop reads that as "confirmed the
+     * pre-picked answers".
+     */
+    async signal(runId, toolCallId, reply) {
         const key = `${runId}:${toolCallId}`;
-        const resolve = this.pending.get(key);
-        if (resolve !== undefined) {
-            this.pending.delete(key);
-            resolve(decision);
+        const parked = this.pending.get(key);
+        if (parked === undefined) {
+            return;
         }
+        if (parked.on === 'approval' && !isHumanDecision(reply)) {
+            throw new HumanReplyMismatchError(runId, toolCallId);
+        }
+        this.pending.delete(key);
+        parked.resolve(reply);
     }
     async cancel(runId) {
         // Best-effort: settle the run `cancelled` (first-terminal, so a completed run stays completed),
@@ -54,38 +89,89 @@ export class InlineAgentRunner {
         const writer = await deps.sink.open(runId);
         await writer.end();
     }
-    topLevelHooks(runId, deps, actor, day) {
+    topLevelHooks(args) {
+        const { runId, deps, actor, day, chainBelow, depth } = args;
         return {
             runId,
             durable: false,
             openSink: () => deps.sink.open(runId),
-            awaitApproval: (call) => new Promise((resolve) => {
-                // Run-namespaced key: `${runId}:${toolCallId}` — one run can't approve another's tool call.
-                this.pending.set(`${runId}:${call.id}`, resolve);
-            }),
+            ...this.humanHooks(runId),
             step: (_name, fn) => fn(),
-            runAgent: (agentName, task) => this.runNested(agentName, task, actor, day),
+            // Nothing here records a position, so a turn's read tools can simply overlap.
+            parallel: settleAll,
+            runAgent: (agentName, task) => this.runNested({
+                agentName,
+                task,
+                actor,
+                day,
+                depth: depth + 1,
+                path: chainBelow,
+                parentRunId: runId,
+                // This run owns the stream a human subscribed to, so every delegation below it writes here.
+                sinkRunId: runId,
+            }),
         };
     }
+    /**
+     * The two waits a run parks on, keyed by the run that is parked. Identical for a top-level run and
+     * for a delegated one: `signal(runId, …)` finds either, because the pending map belongs to the
+     * runner rather than to a run.
+     */
+    humanHooks(runId) {
+        return {
+            awaitApproval: (call) => 
+            // Run-namespaced key: `${runId}:${toolCallId}` — one run can't approve another's tool call.
+            this.park(`${runId}:${call.id}`, 'approval'),
+            // An answer and an approval reach a parked run by the same channel, because a question set is
+            // itself a `pending_approval` row: `POST /agent/tool-call/answer` and `/approve` both land here.
+            awaitAnswers: (request) => this.park(`${runId}:${request.id}`, 'answers'),
+        };
+    }
+    /** Hold a run at `key` until a human's reply arrives through {@link InlineAgentRunner.signal}. */
+    park(key, on) {
+        return new Promise((resolve) => {
+            this.pending.set(key, { on, resolve });
+        });
+    }
     /** Delegate to another agent as a nested in-process run (a transient sub-thread). */
-    async runNested(agentName, task, actor, day) {
+    async runNested(args) {
+        const { agentName, task, actor, day, depth, path, parentRunId, sinkRunId } = args;
         const subThread = await this.store.createThread({ actor, persona: 'default', transient: true });
         const runId = crypto.randomUUID();
         const deps = this.factory.forAgent(agentName);
         const hooks = {
             runId,
             durable: false,
-            openSink: () => deps.sink.open(runId),
-            // A nested sub-agent has no human to ask — decline action tools rather than hang.
-            awaitApproval: async () => ({
-                approved: false,
-                reason: 'nested sub-agent cannot request human approval',
-            }),
+            // Forward into the ancestor's stream but never end it: the top-level run owns that lifecycle
+            // across however many delegations it spans.
+            openSink: async () => childSinkWriter(await deps.sink.open(sinkRunId)),
+            // A delegated run parks on a human like any other, keyed by ITS OWN runId — which is the id
+            // its pending row and its forwarded frames both carry, so the wait can be answered.
+            ...this.humanHooks(runId),
             step: (_name, fn) => fn(),
-            runAgent: (childName, childTask) => this.runNested(childName, childTask, actor, day),
+            parallel: settleAll,
+            runAgent: (childName, childTask) => this.runNested({
+                agentName: childName,
+                task: childTask,
+                actor,
+                day,
+                depth: depth + 1,
+                path: [...path, agentName],
+                parentRunId: runId,
+                sinkRunId,
+            }),
         };
         // A nested sub-agent run is its own trace (its own runId), rooted by the same turn span.
-        return spannedAgent('turn', runId, { runId }, () => runAgentLoop({ ...deps, day }, { threadId: subThread.id, actor, userText: task, agentName, day }, hooks), (result) => ({ textLength: result.text.length }));
+        return spannedAgent('turn', runId, { runId }, () => runAgentLoop({ ...deps, day }, {
+            threadId: subThread.id,
+            actor,
+            userText: task,
+            agentName,
+            day,
+            parentRunId,
+            delegationDepth: depth,
+            delegationPath: path,
+        }, hooks), (result) => ({ textLength: result.text.length }));
     }
 }
 //# sourceMappingURL=inline-agent-runner.js.map

package/dist/src/runners/inline-agent-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"inline-agent-runner.js","sourceRoot":"","sources":["../../../src/runners/inline-agent-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inline-agent-runner.js","sourceRoot":"","sources":["../../../src/runners/inline-agent-runner.ts"],"names":[],"mappings":"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"}

package/dist/src/skills.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Skills: an authored procedure the model pulls in when a task calls for it, instead of every
+ * instruction living in the system prompt.
+ *
+ * WHAT A SKILL IS NOT: an agent. An agent is WHO is answering — its persona, its tools, its history
+ * window, its output schema. A skill is HOW one particular task is done, and any agent may pull one
+ * in. That is why a skill carries no model, no tool list and no schema: the moment it did, the two
+ * would be the same thing wearing different names, and a consumer would have to choose between them
+ * for reasons nobody could state.
+ *
+ * WHAT IT COSTS THE PROMPT: one line per skill. The catalog block below carries names, scopes and
+ * descriptions only; a BODY reaches the model as a tool result, on the transcript, where the
+ * `HistoryWindow` ceiling already governs it. So skills are not a fourth thing competing for the
+ * system block with the agent's own prompt, its persona and injected retrieval — see
+ * `AgentLoopDeps.skills` for how they compose.
+ */
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Actor, PageContext, ToolDefinition } from './types.js';
+/** How a skill is identified in the catalog, to the model and to a `/`-autocomplete alike. */
+export interface SkillSummary {
+    /** Unique within a scope. The handle the model passes to the `skill` tool. */
+    name: string;
+    /** One line: what task this covers, and therefore when to load it. Read by the MODEL to choose. */
+    description: string;
+    /** The opaque scope token this skill is published at — see {@link ScopeResolver}. */
+    scope: string;
+}
+/** A skill with the instructions themselves. Only ever materialized when something loads it. */
+export interface Skill extends SkillSummary {
+    body: string;
+}
+/** Whose turn is asking, and therefore which scopes apply. */
+export interface ScopeContext {
+    actor: Actor;
+    threadId: string;
+    /** The agent running this turn. Undefined → the default agent. */
+    agentName?: string;
+    pageContext?: PageContext;
+}
+/**
+ * The skills-facing name for {@link ScopeContext}, so a `SkillProvider`'s signature reads in its own
+ * vocabulary. Deliberately the SAME type rather than a parallel one: skills and memory resolve
+ * scopes through one {@link ScopeResolver}, and a deployment that could answer "which scopes does
+ * this actor have" twice would eventually answer it differently.
+ */
+export type SkillContext = ScopeContext;
+/** The scope token every deployment has: skills nobody narrowed. */
+export declare const GLOBAL_SCOPE = "global";
+/** The token for one actor's own skills. */
+export declare function actorScope(actor: Actor): string;
+/** The token for a tenant's skills — `Actor.tenantRef` is the only tenant key this library knows. */
+export declare function tenantScope(tenantRef: string): string;
+/**
+ * Which scopes a turn may draw from, MOST SPECIFIC FIRST. Precedence is the order: an entry from an
+ * earlier token outranks a same-named one from a later token, and the model is shown which won.
+ *
+ * A HOST-SUPPLIED FUNCTION rather than an enum this library owns, because the axes a deployment
+ * scopes by are the deployment's own. `Actor` gives an id and a tenant; it does not give a sector, a
+ * squadron, a base, a shift — and every one of those is a real axis in some consumer. An enum here
+ * would make each of them a schema change in a library that has no business knowing they exist,
+ * while a token is a string a host mints for itself. Return `['sector:logistics', 'tenant:base-7',
+ * 'global']` and precedence follows, with nothing in this package edited.
+ *
+ * MUST be a pure function of its context. It runs inside the `skills:catalog` / `memory:digest`
+ * checkpoint and its result is journaled, so a resumed run reads back the scopes the first attempt
+ * resolved rather than asking a membership table that may have changed since — which would let a
+ * run's prompt differ from the one its journal records. Read a database here at your peril; read it
+ * in the provider, whose answer is journaled at the same position.
+ */
+export interface ScopeResolver {
+    resolve(ctx: ScopeContext): string[] | Promise<string[]>;
+}
+/**
+ * The scopes derivable from an {@link Actor} alone — the common case, so a consumer wiring skills
+ * for the first time supplies no resolver at all: the actor's own, their tenant's (when they have
+ * one), and the deployment's. A host adding an axis of its own replaces this rather than extending
+ * it, since the ORDER is the precedence and only the host knows where its axis belongs.
+ */
+export declare const defaultScopeResolver: ScopeResolver;
+/** Arguments to {@link SkillProvider.list}. */
+export interface ListSkillsInput {
+    scopes: readonly string[];
+    ctx: SkillContext;
+}
+/**
+ * Arguments to {@link SkillProvider.load}. An object rather than positional arguments because `name`
+ * and `scope` are both strings: transposed, a positional call compiles clean, returns `null`, and
+ * the skill silently fails to load.
+ */
+export interface LoadSkillInput {
+    name: string;
+    scope: string;
+    ctx: SkillContext;
+}
+/**
+ * Where skills come from. Deliberately two calls rather than one: `list` is asked on EVERY turn and
+ * must stay cheap, while a body is read only when the model decides it needs that procedure — the
+ * whole point of the surface. A provider over a table selects name/description/scope for the first
+ * and one row for the second.
+ *
+ * This library owns no skill table. A skill's real scoping axes, its authoring UI and its audit
+ * trail are all the host's, and a host that related its own entity into a table this package created
+ * at boot would be writing migrations against a schema the boot-time heal also edits. Tokens split
+ * it the other way round: the library owns the contract (what a scope means, how precedence works,
+ * what is journaled), the host owns the rows.
+ */
+export interface SkillProvider {
+    /**
+     * Every skill visible at `scopes`, in any order — this library sorts and resolves precedence. A
+     * provider MAY return skills outside `scopes`; they are dropped rather than trusted, so a filter
+     * bug in a host cannot widen what an actor is offered.
+     */
+    list(input: ListSkillsInput): SkillSummary[] | Promise<SkillSummary[]>;
+    /**
+     * The instructions for one skill, or `null` when it is gone. Called only from inside the loading
+     * checkpoint, so the body it returns is journaled and every replay reads THAT text back — an
+     * edited skill never rewrites the prompt of a run already in flight.
+     */
+    load(input: LoadSkillInput): string | null | Promise<string | null>;
+}
+/** A source of skills that is a fixed list — module config, or a host's own constant. */
+export declare function staticSkillProvider(skills: readonly Skill[]): SkillProvider;
+/**
+ * Read several sources as one. The order is the tie-break and nothing else: precedence between
+ * skills is by SCOPE, so two sources only ever compete when they publish the same name at the same
+ * scope, and then the earlier source wins. Wire the host's own provider first — a row it can edit is
+ * a better answer than a body that needs a deploy to change.
+ */
+export declare function compositeSkillProvider(providers: readonly SkillProvider[]): SkillProvider;
+/**
+ * One skill as it is offered — to the model in the catalog block, and to a client listing what a
+ * user may type after a `/`. Both read the same list, built by the same call, so what a user can
+ * reach and what the model can reach cannot drift apart.
+ */
+export interface SkillCatalogEntry {
+    name: string;
+    description: string;
+    /** The scope token it resolved from — the provenance a user is entitled to see. */
+    scope: string;
+    /**
+     * Scope tokens of same-named skills this one outranks, widest last. Present ONLY when something
+     * was shadowed, so a reader can tell "there is no org default" from "there is one and yours wins".
+     * The model is shown it for the same reason: a silent override is indistinguishable from an
+     * instruction nobody wrote, and the user can only be told "your setting differs from the org
+     * default" by something that knows both existed.
+     */
+    shadows?: string[];
+}
+/** What a turn resolved — journaled whole, so the prompt is reconstructible from the journal alone. */
+export interface SkillOffer {
+    /** The scope tokens this turn drew from, most specific first. */
+    scopes: string[];
+    /** The skills offered, most specific first then by name. */
+    entries: SkillCatalogEntry[];
+    /** Applicable skills `maxSkills` left out. Non-zero means the catalog is not the whole truth. */
+    omitted: number;
+}
+/**
+ * How many skills a catalog offers before it starts leaving some out. A ceiling on the SYSTEM
+ * PROMPT's share, not on how many a deployment may have: the block costs one line each, and a
+ * hundred lines of "here is something you could load" crowds out the agent's own instructions while
+ * making the choice harder rather than easier.
+ */
+export declare const DEFAULT_MAX_SKILLS = 20;
+/** How a turn reaches its skills. See `AgentLoopDeps.skills`. */
+export interface SkillsConfig {
+    provider: SkillProvider;
+    /** Undefined → {@link defaultScopeResolver}: the actor's own, their tenant's, the deployment's. */
+    scopes?: ScopeResolver;
+    /** Undefined → {@link DEFAULT_MAX_SKILLS}. */
+    maxSkills?: number;
+}
+/**
+ * Resolve a provider's skills against an ordered scope list: most specific wins, and the loser's
+ * scope is recorded rather than discarded.
+ *
+ * Pure, and separately exported, because two callers must reach the identical answer — the loop, so
+ * the model is offered it, and the listing endpoint, so a user is. A second implementation of "which
+ * skills apply" is a second answer, and the two diverge the first time either is edited.
+ */
+export declare function resolveSkillCatalog(summaries: readonly SkillSummary[], scopes: readonly string[], maxSkills?: number): Omit<SkillOffer, 'scopes'>;
+/** Resolve the scopes and the catalog for one turn. Called INSIDE the loop's `skills:catalog` step. */
+export declare function offerSkills(config: SkillsConfig, ctx: SkillContext): Promise<SkillOffer>;
+/** The reserved name of the built-in skill-loading tool. */
+export declare const SKILL_TOOL_NAME = "skill";
+/**
+ * The catalog as the model reads it. One line per skill — name, scope, description, and what it
+ * overrides — because the entire claim of progressive disclosure is that choosing what to read costs
+ * far less than reading everything.
+ */
+export declare function buildSkillsBlock(entries: readonly SkillCatalogEntry[]): string;
+/** What the model passes to the `skill` tool. */
+export interface SkillToolInput {
+    name: string;
+}
+/**
+ * The `skill` tool's input schema. Hand-written for the same reason `askInputSchema` is: this
+ * package depends on no validator, and the schema has to publish a JSON Schema a provider can
+ * constrain generation against.
+ *
+ * The available names are deliberately NOT an enum here. A per-turn enum would make the tool's
+ * definition depend on the catalog, and a tool list re-derived by whichever process serves a turn is
+ * exactly the process-local lookup this design keeps off a turn's decisions. The names live in the
+ * prompt, where the journal holds them; a name that is not in the catalog comes back as an ordinary
+ * tool failure listing the ones that are.
+ */
+export declare const skillInputSchema: StandardSchemaV1<unknown, SkillToolInput>;
+export declare const SKILL_TOOL_DESCRIPTION = "Read one of the procedures listed in <skills>. Call it before doing a task a listed skill covers, and follow what it returns. It performs nothing and changes nothing \u2014 it only gives you instructions you do not yet have.";
+/**
+ * The `skill` tool as the model sees it. NOT a `ToolSpec` and never registered, exactly like `ask`:
+ * it has no handler, because the loop serves it from the catalog the journal holds. Keeping it out
+ * of the `ToolRegistry` is also what keeps its kind off a process-local lookup — see
+ * `claimToolCall`.
+ */
+export declare function skillToolDefinition(): ToolDefinition;
+/** What a `skill` call resolved to — the body, or why it did not. */
+export type SkillLoadOutcome = {
+    ok: true;
+    skill: Skill;
+    shadows?: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Serve one `skill` call against the catalog THIS TURN was offered.
+ *
+ * The catalog is the authorization boundary, not just a menu: a name the turn was never offered is
+ * refused here, so a model that invents one (or repeats one it saw in another actor's thread) cannot
+ * reach a body through a provider that would happily serve it. Because the catalog came out of the
+ * `skills:catalog` checkpoint, that boundary is the one the journal records rather than the one this
+ * process's provider currently believes in.
+ */
+export declare function loadSkill(args: {
+    config: SkillsConfig;
+    offer: SkillOffer;
+    name: string;
+    ctx: SkillContext;
+}): Promise<SkillLoadOutcome>;
+/** Who is trying to write a skill. */
+export interface SkillAuthor {
+    /**
+     * `'human'` is a person acting through a UI; `'agent'` is anything else — a tool, a turn, a batch
+     * job. The distinction is the whole of the rule below, so it is not inferable and has to be stated
+     * by the caller.
+     */
+    kind: 'human' | 'agent';
+    actorRef?: string;
+}
+/** A request to author a skill at a scope. */
+export interface SkillWriteRequest {
+    /** The scope token the skill would be published at. */
+    scope: string;
+    actor: Actor;
+    /** The actor's resolved scopes, most specific first — the same list a turn draws from. */
+    scopes: readonly string[];
+    author: SkillAuthor;
+    /**
+     * The host's own answer to "may this person administer that scope" — a sector lead editing their
+     * sector's skills, an operator editing the deployment's. This library cannot know it: it has no
+     * notion of who administers `sector:logistics`, and inventing one would be a second, weaker
+     * authorization model next to the host's real one. Undefined/false → a wider scope is refused.
+     */
+    elevated?: boolean;
+}
+export type SkillWriteVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * May this author publish a skill at this scope?
+ *
+ * A skill's body is instructions the model follows, which makes writing one at a scope an edit to
+ * everyone in that scope's system prompt. The rules follow from that, and only the third is
+ * interesting:
+ *
+ * 1. You may only write into a scope you are yourself in. Writing into a scope you are not in is
+ *    authoring for people you have no relationship with.
+ * 2. Your OWN scope is yours. A per-actor skill affects exactly one prompt — the author's.
+ * 3. NOTHING BUT A HUMAN MAY WRITE ABOVE ITS OWN SCOPE, whatever `elevated` says. An agent that can
+ *    write a `tenant:` skill is an agent whose prompt anyone in the tenant can edit by talking to
+ *    it: the user asks for something, the turn writes the instruction, and every later turn for
+ *    every other user follows it. That is prompt injection with persistence, and no elevation a host
+ *    could grant makes it a different shape. An agent that has genuinely learned something worth
+ *    sharing proposes it; a person publishes it.
+ * 4. A human writing above their own scope needs the host to say so (`elevated`).
+ */
+export declare function skillWriteVerdict(request: SkillWriteRequest): SkillWriteVerdict;
+//# sourceMappingURL=skills.d.ts.map

package/dist/src/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/src/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/src/spi/agent-runner.d.ts

@@ -1,10 +1,12 @@
-import type { AgentRunInput, Decision } from '../types.js';
+import type { HumanReply } from '../elicitation.js';
+import type { AgentRunInput } from '../types.js';
 /**
  * Runs an agent turn. Two impls exist:
  *  - InlineAgentRunner (default): the loop runs in-process — no extra dependencies. This is what
- *    `AGENT_RUNNER` binds to unless `durable: true` is set.
- *  - DurableAgentRunner (opt-in via `durable: true`): the turn is a `@dudousxd/nestjs-durable`
- *    `@Workflow`, so each model/tool call is a checkpointed step and HITL is `ctx.waitForSignal`.
+ *    the provider builds unless `durable: true` is set.
+ *  - DurableAgentRunner (opt-in via `durable: true`): the turn is an `@adonis-agora/durable`
+ *    {@link import('../durable/agent-run-workflow.js').AgentRunWorkflow}, so each model/tool call is
+ *    a checkpointed step and HITL is `ctx.waitForSignal`.
  *
  * `start` ENQUEUES and returns immediately with the runId — the live tokens flow on the
  * TokenStreamSink, not through this call.
@@ -13,8 +15,20 @@ export interface AgentRunner {
     start(input: AgentRunInput): Promise<{
         runId: string;
     }>;
-    /** Deliver a HITL decision for a pending action tool call. */
-    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
+    /**
+     * Deliver a human's reply to a parked tool call — an approve/reject {@link import('../types.js').Decision}
+     * for an `action`, or an {@link import('../elicitation.js').ElicitationReply} for a question set.
+     * One channel for both, because a question set parks as a `pending_approval` action and therefore
+     * reaches a run through the inbox a deployment already has.
+     *
+     * A `Decision` reaching a question set is the documented reduction ("confirmed the pre-picked
+     * answers"). The reverse is not: answers carry no `approved`, so an implementation that can tell
+     * which wait it is settling MUST refuse them with
+     * {@link import('../elicitation.js').HumanReplyMismatchError} rather than deliver them. An
+     * implementation that cannot tell delivers, and the loop discards the reply and stays parked —
+     * either way, no rejection is recorded against a human who only submitted a form.
+     */
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
     cancel(runId: string): Promise<void>;
 }
 //# sourceMappingURL=agent-runner.d.ts.map