agentfootprint 10.3.0 → 10.3.1

package/dist/types/injection-engine/skillSteps.d.ts

@@ -0,0 +1,229 @@
+/**
+ * skillSteps — the procedure grammar (9.18.0). ONE owner of everything
+ * "steps as data": the types, the validation, the step pointer's shape and
+ * re-key rule, the `skip_step` integrity tool, and EVERY sentence the model
+ * reads about a procedure (the banner, the result suffixes, the skip
+ * sentences, the nudge). Stages and slots call in here; none of them owns
+ * a word of the grammar.
+ *
+ * WHAT A PROCEDURE IS. `defineSkill({ steps })` declares an ordered list of
+ * `{ tool, note }` pairs — "run these tools, in this order, for these
+ * reasons". The framework then OWNS sequence and scope at the protocol
+ * level: while a stepped skill holds the tenure, the tools slot offers only
+ * the current step's tool (plus every escape hatch — see below), so the
+ * model cannot call step 5's tool from step 3 because step 5's schema was
+ * never sent. No refusal machinery, no new gate: an unoffered tool is
+ * uncallable by construction.
+ *
+ * WHAT THE MODEL STILL OWNS: judgment inside the step. It can run the tool,
+ * skip it with a recorded reason (`skip_step`), work around it with an
+ * escape hatch, or stop and say why. The escape hatches are load-bearing
+ * and stay offered under narrowing: `read_skill`, `list_skills`, every
+ * OTHER active skill's tools, the baseline `.tool()` registry, provider
+ * tools. A procedure is a declared order, not a cage.
+ *
+ * THE POINTER. `AgentState.stepPointer` records where the procedure stands:
+ * `{ skillId, step, total, skipped }`, 1-based, `step === total + 1` means
+ * complete. It is strictly SUBORDINATE to the one skill-graph cursor: it
+ * lives and dies inside one skill's tenure, is re-keyed at the same stage
+ * the cursor truth lives (Evaluate), and never crosses runs. It can never
+ * move the cursor.
+ *
+ * CARRIER SHAPE (load-bearing): the pointer travels through scope and the
+ * mount mappers as a 0-or-1-element ARRAY (`StepPointerCarrier`), never as
+ * a bare object. footprintjs's `applyOutputMapping` shallow-merges bare
+ * object values field-by-field — and APPENDS nested arrays — so a re-keyed
+ * pointer mapped as an object would inherit the previous tenure's `skipped`
+ * entries. A top-level array under `arrayMerge: Replace` is set wholesale.
+ * `[]` = the feature is on and no procedure is active; the key is absent
+ * entirely on agents with no stepped skill (zero-cost-when-unused).
+ */
+import type { SkillToolDescriptor } from './hostContract.js';
+import type { Injection } from './types.js';
+/** One step of a declared procedure. */
+export interface SkillStep {
+    /** The tool this step runs. MUST be one of this skill's own `tools` —
+     *  refused at `defineSkill` otherwise. Repeats across steps are legal
+     *  ("look it up again after the change"). */
+    readonly tool: string;
+    /** Why/what — the sentence the model sees ("look up the order before
+     *  touching money"). Required, non-empty: a step with no note is a
+     *  force-march instruction, and the note is the whole point. */
+    readonly note: string;
+    /**
+     * Artifact KINDS this step leaves behind (9.25.0) — a declaration, not
+     * machinery: nothing at run time reads it, and a step without it is
+     * byte-identical to today. It makes the step's data leg checkable at build
+     * (`artifact-kind-unsatisfied`) and drawable by a lens. See
+     * `skillVocabulary.ts` for the satisfiability rule and its boundaries.
+     */
+    readonly produces?: readonly string[];
+    /**
+     * Artifact KINDS this step needs to have arrived (9.25.0). Satisfiable
+     * three ways — by an EARLIER step of the same skill, by the skill's own
+     * `consumes` (it arrived from outside), or by the step's tool declaring
+     * `wants` for the kind (the framework redeems that ref at dispatch, from a
+     * store that outlives the turn). Anything else is a build-time WARNING.
+     */
+    readonly consumes?: readonly string[];
+}
+/**
+ * What the framework does when the model skips a step with `skip_step`:
+ *
+ * - `'advance'` (default) — record the skip and move to the next step;
+ * - `'hold'` — record the skip and keep the step current (its tool stays
+ *   the offer; the model may retry it, work around it with the escape
+ *   hatches, or finish and explain).
+ */
+export type OnSkipPolicy = 'advance' | 'hold';
+/**
+ * WHERE a declared procedure stands. 1-based; `step === total + 1` means
+ * the procedure completed. `skipped` holds the indexes the model skipped
+ * under the `'advance'` policy (a `'hold'` skip is recorded on the event
+ * stream, not here — the pointer did not move).
+ */
+export interface StepPointer {
+    /** The tenant this pointer belongs to — the stepped skill whose tenure
+     *  is current. A cursor move away from it resets the pointer. */
+    readonly skillId: string;
+    /** Current step, 1-based. `total + 1` = procedure complete. */
+    readonly step: number;
+    readonly total: number;
+    /** Step indexes skipped-with-reason that the pointer moved past. */
+    readonly skipped: readonly number[];
+}
+/**
+ * How the pointer travels through scope and every mount mapper: a
+ * 0-or-1-element array. See the module docstring for why a bare object
+ * cannot cross a footprintjs outputMapper safely.
+ */
+export type StepPointerCarrier = readonly StepPointer[];
+/** The build-time fold of one stepped skill — frozen at `Agent` build. */
+export interface StepPlan {
+    readonly skillId: string;
+    readonly steps: readonly SkillStep[];
+    /** Every tool name the plan's steps name — the hold-out candidates. */
+    readonly toolNames: ReadonlySet<string>;
+    readonly onSkip: OnSkipPolicy;
+}
+/** The lookup the engine, the tools slot and the tool-calls stage share.
+ *  Undefined ⇒ no skill on this agent declares steps (the zero-cost gate). */
+export type StepPlanFor = (skillId: string) => StepPlan | undefined;
+/** The integrity tool's reserved name. Auto-attached (dispatchable) when
+ *  ≥1 registered skill declares steps; OFFERED only while a stepped tenure
+ *  is active and unfinished. */
+export declare const SKIP_STEP_TOOL_NAME = "skip_step";
+/**
+ * Validate a `steps` declaration against the skill's own tools. All the
+ * data is in hand at `defineSkill`, so every refusal happens there — the
+ * `body-unknown-tool` sibling.
+ */
+export declare function validateSkillSteps(skillId: string, opts: {
+    readonly steps?: readonly SkillStep[];
+    readonly onSkip?: OnSkipPolicy;
+    readonly toolNames: ReadonlySet<string>;
+}): void;
+/** Read a skill injection's declared steps off its metadata bag (the
+ *  `autoActivate` precedent — the engine ignores unknown keys). */
+export declare function stepsOf(injection: Injection): {
+    readonly steps: readonly SkillStep[];
+    readonly onSkip: OnSkipPolicy;
+} | undefined;
+/**
+ * Fold every stepped skill into one frozen plan map. Runs once at
+ * `Agent` build; the map is threaded as closures — nothing rides
+ * `projectActiveInjection`, so the projection allow-list is untouched.
+ * Empty map ⇒ the feature is off everywhere (callers thread nothing).
+ */
+export declare function foldStepPlans(injections: readonly Injection[]): ReadonlyMap<string, StepPlan>;
+/** Unwrap the carrier. `undefined` for an absent key, an empty carrier,
+ *  or a value that is not a carrier at all. */
+export declare function pointerOf(carrier: unknown): StepPointer | undefined;
+/** True while the procedure has steps left (`step <= total`). A completed
+ *  pointer stays on scope as the record; nothing narrows or nudges on it. */
+export declare function stepInProgress(ptr: StepPointer | undefined): ptr is StepPointer;
+/** The current step's declaration, when the procedure is in progress. */
+export declare function currentStepOf(ptr: StepPointer, plan: StepPlan): SkillStep | undefined;
+/**
+ * The tenure RE-KEY — Evaluate's half of the pointer discipline.
+ *
+ * `tenant` is who holds the tenure THIS iteration: the advanced cursor on
+ * graph agents, else the tail of `activatedInjectionIds` (the shipped
+ * `activeSkillId` notion). Tenant changed → a fresh pointer when the new
+ * tenant declares steps, else cleared. Tenant unchanged → pass-through.
+ * Always returns a carrier (possibly empty) — the caller writes it every
+ * iteration the feature is on, so downstream readers never see a stale one.
+ */
+export declare function rekeyStepPointer(args: {
+    readonly prior: StepPointerCarrier | undefined;
+    readonly tenant: string | undefined;
+    readonly stepPlanFor: StepPlanFor;
+}): StepPointerCarrier;
+/**
+ * DESCRIBE the `skip_step` tool — name, schema, and the placeholder result.
+ *
+ * A description, not a tool: this module owns every sentence the model reads
+ * about a procedure, and that includes this one, but building the framework's
+ * tool object would mean importing the framework's tool factory into the
+ * grammar. `skillTools.ts#buildSkipStepTool` does the wrapping (9.34.0).
+ *
+ * The tool is auto-attached to the dispatch registry when ≥1 registered skill
+ * declares steps (the `read_skill` auto-attach seam) — always dispatchable,
+ * but OFFERED (schema in the request) only while a stepped tenure is active
+ * and unfinished. Its execute returns a placeholder; the tool-calls stage
+ * overwrites the model-visible result with the authoritative sentence,
+ * exactly as the skill-graph gate overwrites `read_skill` refusals —
+ * bookkeeping lives where the batch order lives.
+ */
+export declare function skipStepDescriptor(): SkillToolDescriptor<{
+    reason: string;
+}, string>;
+/** `[Step 3 of 6 — <note>] ` — prefixed onto the current step's tool
+ *  description in the offer (a rebuilt schema copy, substituted by name). */
+export declare function stepBannerPrefix(ptr: StepPointer, step: SkillStep): string;
+/** The per-iteration `skip_step` offer description: names the current
+ *  step, the remaining count, and the declared onSkip policy. */
+export declare function skipStepDescription(ptr: StepPointer, plan: StepPlan): string;
+/** Suffix for the `read_skill` result that activated a stepped skill:
+ *  where the procedure starts. */
+export declare function readSkillStepIntro(plan: StepPlan): string;
+/** Suffix for a completed step's tool result: done + what is next. */
+export declare function stepAdvanceSuffix(next: StepPointer, plan: StepPlan): string;
+/** The authoritative `skip_step` result under the `'advance'` policy. */
+export declare function skipAdvanceSentence(skippedIndex: number, reason: string, next: StepPointer, plan: StepPlan): string;
+/** The authoritative `skip_step` result under the `'hold'` policy. */
+export declare function skipHoldSentence(ptr: StepPointer, reason: string, plan: StepPlan): string;
+/** Teaching result for `skip_step` with an empty reason — no event. */
+export declare function skipNeedsReasonSentence(): string;
+/** Teaching result for `skip_step` outside a stepped tenure — no event. */
+export declare function skipNothingActiveSentence(): string;
+/** The remaining (unrun) steps — the `steps_unfinished` payload's list and
+ *  the nudge's material. Under `'advance'` a skipped step is behind the
+ *  pointer and therefore never "remaining". */
+export declare function remainingStepsOf(ptr: StepPointer, plan: StepPlan): ReadonlyArray<{
+    readonly index: number;
+    readonly tool: string;
+    readonly note: string;
+}>;
+/**
+ * The one teaching nudge for a premature stop (at most once per turn).
+ *
+ * Written as an AUTHORED FRAME (9.86.0). `stepNudge` appends the result to
+ * `scope.history` wearing `role: 'user'`, so two things follow. First, it has
+ * to be recognisable as this library's own writing: it opens with
+ * {@link STEP_NUDGE_FRAME_PREFIX}, imported from the authorship registry that
+ * `isSaidByPerson` matches against, because the body lists a skill id and
+ * every unrun step's TOOL NAME — exactly the text a routing rule scanning
+ * history watches for, and before the opening was here such a rule fired on
+ * the library's own nudge.
+ *
+ * Second, it is re-read on every later call of the turn, so it may not speak
+ * in the present or issue a standing instruction: "Steps 2–3 have not run …
+ * Finish them" is false the moment they run, and it was still sitting in
+ * `history` when they did. Every clause now reports the call the nudge was
+ * written for, in the past tense, and the ask is stated as what THAT call was
+ * for. Pinned by `test/injection-engine/userTurnProducers.test.ts`, which
+ * runs the composed sentence through `unprovable`.
+ */
+export declare function nudgeTeachingMessage(ptr: StepPointer, plan: StepPlan): string;
+//# sourceMappingURL=skillSteps.d.ts.map

package/dist/types/injection-engine/skillSteps.d.ts.map

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

package/dist/types/injection-engine/skillToolDescriptors.d.ts

@@ -0,0 +1,169 @@
+/**
+ * skillToolDescriptors — the graph DESCRIBING the tools it needs (9.34.0).
+ *
+ * `read_skill` is not an ordinary tool. It is how the model asks to move the
+ * skill-graph cursor: its enum is the catalog, its description is the offer
+ * (what is reachable from here, what will be refused, what this turn's menu
+ * proposes), and its result is what the model reads about the skill it just
+ * activated. Every one of those sentences is the GRAPH's to write.
+ *
+ * What the graph must NOT do is construct a framework's tool object. That is
+ * why this module produces {@link SkillToolDescriptor} POJOs — name,
+ * description, input schema, a pure `execute` — and `skillTools.ts` (the host
+ * adapter) is the one line that turns each into an agentfootprint `Tool` with
+ * `defineTool`. A host on another framework calls the same functions and
+ * wraps the result in its own tool type instead.
+ *
+ * ONE catalog, ONE grammar: the Agent's auto-attach path, `SkillRegistry`
+ * and any foreign host all read the descriptions from here, so they cannot
+ * drift the way a second hand-written `read_skill` would.
+ *
+ * Zone: PURE CORE. Pinned by
+ * `test/injection-engine/skill-graph-fence.test.ts`.
+ */
+import type { SkillToolDescriptor } from './hostContract.js';
+import type { Injection } from './types.js';
+/**
+ * What the gate will ACTUALLY grant right now — the ids `read_skill` should be
+ * offering, as opposed to the ids it can dispatch (8.5.0).
+ *
+ * Without this the tool enumerated every registered skill while the skill-graph gate
+ * admitted only `reachableSkills(cursor) ∪ open`, so a route target the cursor cannot
+ * reach was advertised on every iteration and refused on every call. The model was
+ * being asked to choose from a menu the library knew it would reject.
+ */
+export interface ReadSkillOffer {
+    /**
+     * Ids the gate will grant from the current cursor. Omit when there is no
+     * graph — then the description is the plain catalog it has always been,
+     * minus anything {@link ReadSkillOffer.hiddenIds} removes.
+     */
+    readonly grantable?: readonly string[];
+    /** Say the rest are refusable rather than hiding them. Hiding a skill it can see
+     *  in `list_skills` (and in the enum) would just move the confusion; naming the
+     *  boundary lets the model route around it in one step instead of guessing. */
+    readonly showRefusable?: boolean;
+    /**
+     * Ids removed from the description ENTIRELY — not listed as reachable, not
+     * listed as refusable, not named at all (9.11.0).
+     *
+     * The opposite treatment from the graph's `shut` set above, and deliberately
+     * so. A graph refusal is about WHERE THE CURSOR IS: the skill exists for this
+     * caller, it is simply not reachable from here, so naming it lets the model
+     * route to it in one step. A hidden skill is about WHO IS ASKING: no cursor
+     * move makes it available, and naming it would tell a role about a capability
+     * it will never be allowed to use — leaking the shape of somebody else's
+     * permissions into this model's prompt.
+     *
+     * The ENUM keeps the full catalog either way (see below). Narrowing it would
+     * turn a policy refusal into a generic schema error, and the model would
+     * never read the policy's own message.
+     */
+    readonly hiddenIds?: readonly string[];
+    /**
+     * WHERE THE CURSOR STANDS — the skill the model is already IN (9.84.0).
+     *
+     * Passed on every call that has a cursor, menu or no menu. It does two jobs
+     * the offer could not do before: it NAMES the current skill in the
+     * description (previously only the menu's stay clause ever did, and a
+     * decisively-routed turn has no menu), and it keeps that skill out of the
+     * "Not reachable from here" list — where it appeared purely as an artefact of
+     * being filtered out of its own successor set.
+     *
+     * {@link ReadSkillOffer.menu}'s `cursorId` is the same value and still
+     * honoured; this one is simply not conditional on a menu being outstanding.
+     *
+     * It is NOT exempt from {@link ReadSkillOffer.hiddenIds}. A cursor the
+     * caller's role may not see is not named — see the filter in `describeOffer`.
+     */
+    readonly cursorId?: string;
+    /**
+     * Turn-start MENU (SG-C): when set, the description LEADS with these
+     * candidates (id + one-line description; supplied advisory relevance %s),
+     * names the cursor, and states STAY as a first-class
+     * option ("answer without calling read_skill to stay in '<cursor>'").
+     *
+     * Set only while the turn's menu verdict is outstanding (turn start, before
+     * any accepted pick) — the tools slot reads it off the SAME verdict the
+     * record carries, so the offer can never drift from `turn_routed.offered`.
+     * The enum stays the full catalog (the 8.5.0 law below — narrowing it would
+     * retire four honesty mechanisms), and {@link ReadSkillOffer.hiddenIds}
+     * filters menu rows exactly as it filters every other list: a role-hidden
+     * skill is never NAMED, menu or no menu.
+     * Descriptions appear once per skill id in this offer. Later catalog or
+     * reachability rows retain the id and refer to its description above.
+     */
+    readonly menu?: {
+        readonly candidates: ReadonlyArray<{
+            readonly id: string;
+            readonly relevance?: number;
+        }>;
+        /** Names the cursor the STAY sentence refers to ("you are in billing"). */
+        readonly cursorId?: string;
+        /** STAY spelled out as a first-class option (mid-conversation menus). */
+        readonly stay?: boolean;
+    };
+    /**
+     * The mounted graph is a decision `tree()` (9.86.0).
+     *
+     * A tree routes by predicate on every iteration and keeps no cursor, so
+     * `reachableSkills()` is empty from every position and EVERY routing pick is
+     * refused by construction. Offering `read_skill` anyway asked the model to
+     * choose from a menu the library knew it would reject — the same defect
+     * 8.5.0 fixed for the flat graph's unreachable ids, left standing for the
+     * one shape where it is total.
+     *
+     * With no open skill left after {@link ReadSkillOffer.hiddenIds}, the tool is
+     * not offered at all ({@link readSkillDescriptor} returns `undefined`); with
+     * open skills, the description says a tree has no cursor to move and names
+     * exactly the skills a pick CAN open. Either way the name stays dispatchable
+     * — position governs the offer, never dispatch — so a model that calls it
+     * from a restored transcript still reads the gate's own refusal.
+     */
+    readonly treeRouted?: boolean;
+}
+/**
+ * Describe the `list_skills` tool — a no-arg tool that returns the registered
+ * skills as `{ id, description }[]`. Lets the LLM discover skills without
+ * paying the prompt-token cost of embedding the catalog into every system
+ * prompt.
+ *
+ * Pairs with {@link readSkillDescriptor} (which actually activates a skill by
+ * id). Returns `undefined` when there are no skills — a tool offering an
+ * empty catalog is noise.
+ */
+export declare function listSkillsDescriptor(skills: readonly Injection[]): SkillToolDescriptor<Record<string, never>, string> | undefined;
+/**
+ * Describe the `read_skill` tool — THE cursor door. The LLM picks WHICH skill
+ * via the `id` argument; the host's loop is what turns an accepted pick into a
+ * cursor move (see `SkillGraphHost`, obligations 2 and 3).
+ *
+ * `execute` returns a confirmation string, or the skill body verbatim for the
+ * `'tool-only'` / `'both'` surface modes (recency-first delivery). The actual
+ * bookkeeping — appending the requested id to the activated set, gating it
+ * against `reachableSkills`, publishing the accepted pick — is the HOST's,
+ * because only the host sees the tool call.
+ *
+ * Pass `offer` to scope the DESCRIPTION to what the graph's gate will actually
+ * grant from the current cursor (8.5.0); the enum stays the full catalog
+ * either way. Omit it and the description is byte-identical to the plain
+ * catalog it has always been.
+ *
+ * Returns `undefined` when there are no skills.
+ */
+export declare function readSkillDescriptor(skills: readonly Injection[], offer?: ReadSkillOffer): SkillToolDescriptor<{
+    id: string;
+}, string> | undefined;
+/**
+ * What `read_skill` answers when it activated a skill but did NOT carry its body
+ * (surface modes `'system-prompt'` / `'auto'` — the body lands via the system
+ * slot next iteration).
+ *
+ * Exported because the skill-graph gate has to tell this sentence apart from a
+ * body: a SELF-CALL keeps the body (the model asked to re-read where it is, and
+ * under `'tool-only'` the tool result is the only place that body ever appears)
+ * but must not keep a promise of an activation that is not pending. Comparing
+ * against the one owner of the string beats guessing at its shape.
+ */
+export declare function skillActivationConfirmation(id: string): string;
+//# sourceMappingURL=skillToolDescriptors.d.ts.map

package/dist/types/injection-engine/skillToolDescriptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillToolDescriptors.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/skillToolDescriptors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;mFAE+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE;QACd,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACzF,2EAA2E;QAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,yEAAyE;QACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;IACF;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAoTD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,SAAS,EAAE,GAC3B,mBAAmB,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,GAAG,SAAS,CAqBhE;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,KAAK,CAAC,EAAE,cAAc,GACrB,mBAAmB,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,CAAC,GAAG,SAAS,CAsEzD;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/types/injection-engine/skillTools.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Skill-tool ADAPTERS — the one place the graph's tool DESCRIPTIONS become
+ * agentfootprint `Tool`s.
+ *
+ * `list_skills`, `read_skill` and `skip_step` are described — name, schema,
+ * every sentence the model reads — by the pure skill-graph core
+ * (`skillToolDescriptors.ts`, `skillSteps.ts`). This module does the last
+ * step: hands each descriptor to `defineTool`. That split (9.34.0) is what
+ * keeps `read_skill`'s grammar, which is genuinely the graph's — the enum is
+ * the catalog, the description is the reachability offer, the result is what
+ * the model learns about the skill it activated — out of a module that has to
+ * import the framework's tool factory, and therefore out of everything that
+ * factory pulls in (artifacts, credentials, check-in, tool sessions).
+ *
+ * Both tool pairs work over the SAME catalog (a list of `Injection` skills),
+ * used by the Agent's auto-attach path AND by `SkillRegistry.toTools()`
+ * (explicit composition path). Pulling them out of `core/Agent.ts` removed
+ * the v2.4 duplication risk: the Agent auto-attaches its own `read_skill`,
+ * the registry builds a sibling — they MUST agree on schema + execute
+ * semantics, and now they cannot disagree because neither writes the words.
+ *
+ * Tool execute is identity-style (returns a confirmation string); the agent's
+ * tool-calls subflow inspects the tool name + args and updates
+ * `scope.activatedInjectionIds` so the next iteration's InjectionEngine sees
+ * the new activation.
+ *
+ * Zone: HOST. Importing `tools/tools.js` here is the point of the file.
+ */
+import type { Tool } from '../tools/tools.js';
+import { type ReadSkillOffer } from './skillToolDescriptors.js';
+import type { Injection } from './types.js';
+export type { ReadSkillOffer } from './skillToolDescriptors.js';
+/**
+ * Build the `list_skills` tool — a no-arg tool that returns the
+ * registered skills as `{ id, description }[]`. Lets the LLM discover
+ * skills without paying the prompt-token cost of embedding the
+ * catalog into every system prompt.
+ *
+ * Pairs with `read_skill` (which actually activates a skill by id).
+ *
+ * Returns `undefined` when there are no skills — callers should
+ * guard or filter undefined out of their tool list.
+ */
+export declare function buildListSkillsTool(skills: readonly Injection[]): Tool | undefined;
+/**
+ * Build the `read_skill` tool — activates a skill for the next
+ * iteration. The LLM picks WHICH skill via the `id` argument.
+ *
+ * Tool execute() returns a confirmation string. The actual bookkeeping
+ * (appending the requested skill id to `scope.activatedInjectionIds`)
+ * is handled by the Agent's tool-calls subflow, which inspects every
+ * `read_skill` tool call by name. The next iteration's InjectionEngine
+ * matches Skills with `trigger.kind: 'llm-activated'` by id and
+ * includes them in the active set; slot subflows then inject the body
+ * + tools.
+ *
+ * The tool's description lists each Skill's `id` + `description` so
+ * the LLM can choose meaningfully without first calling `list_skills`
+ * (a perf trade-off — small registries can afford the inline catalog;
+ * large ones should use `list_skills` for discovery and rely on the
+ * shorter `read_skill` description.) See `surfaceMode` (Block A4) for
+ * tunable trade-offs.
+ *
+ * Returns `undefined` when there are no skills — callers should
+ * guard or filter undefined out of their tool list.
+ *
+ * Pass `offer` to scope the DESCRIPTION to what the graph's gate will actually
+ * grant from the current cursor (8.5.0); the enum stays the full catalog either
+ * way. Omit it and the tool is byte-identical to what it has always been.
+ */
+export declare function buildReadSkillTool(skills: readonly Injection[], offer?: ReadSkillOffer): Tool | undefined;
+/**
+ * Build the `skip_step` tool. Auto-attached to the dispatch registry when
+ * ≥1 registered skill declares steps (the `read_skill` auto-attach seam) —
+ * always dispatchable, but OFFERED (schema in the request) only while a
+ * stepped tenure is active and unfinished. Its execute returns a
+ * placeholder; the tool-calls stage overwrites the model-visible result
+ * with the authoritative sentence, exactly as the skill-graph gate
+ * overwrites `read_skill` refusals — bookkeeping lives where the batch
+ * order lives.
+ *
+ * Lived in `skillSteps.ts` through 9.33.x; moved here in 9.34.0 so that
+ * module — the procedure GRAMMAR — stops importing the tool factory. The
+ * sentences it speaks are still `skillSteps.ts`'s
+ * ({@link skipStepDescriptor}); only the wrapping moved.
+ */
+export declare function buildSkipStepTool(): Tool;
+/**
+ * The pair returned by `SkillRegistry.toTools()`. Either entry may be
+ * undefined when the registry is empty. Consumers typically destructure:
+ *
+ *   const { listSkills, readSkill } = registry.toTools();
+ *   const tools = [listSkills, readSkill, ...other].filter(Boolean) as Tool[];
+ */
+export interface SkillToolPair {
+    /** The `list_skills` tool, or `undefined` if registry is empty. */
+    readonly listSkills: Tool | undefined;
+    /** The `read_skill` tool, or `undefined` if registry is empty. */
+    readonly readSkill: Tool | undefined;
+}
+//# sourceMappingURL=skillTools.d.ts.map

package/dist/types/injection-engine/skillTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillTools.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/skillTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,CASlF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,GAAG,SAAS,CASlB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAQxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,SAAS,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,SAAS,CAAC;CACtC"}

package/dist/types/injection-engine/skillVocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillVocabulary.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/skillVocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAaD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,UAAU,GAAG,UAAU,EAC7B,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACnC,IAAI,CA+BN;AAED;;mEAEmE;AACnE,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,kBAAkB,GAAG,SAAS,CASjF;AA+CD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,YAAY,EAAE,CA2EtF"}