agentfootprint 10.3.0 → 10.3.1

package/dist/injection-engine/skillToolDescriptors.js

@@ -0,0 +1,447 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillActivationConfirmation = exports.readSkillDescriptor = exports.listSkillsDescriptor = void 0;
+const skillGraph_js_1 = require("./skillGraph.js");
+const spokenIds_js_1 = require("../lib/spokenIds.js");
+// FOLD · the one owner of which skills this reader's ROLE may be told about (the hidden filter over the catalog)
+// consumers read this and never re-derive it: `grantableRows`, `describeOffer`, and `cursorLead`,
+// which re-checks the same hidden set before it names a cursor
+// detached: yes — a new filtered array; the caller's own readonly array when nothing is hidden.
+/**
+ * The skills an offer may NAME — the role filter, in one place (9.86.0).
+ *
+ * "Hidden first, so nothing below can name one" is the description's own law,
+ * and the tree arm needs the same answer BEFORE it decides whether there is
+ * anything left to offer. Two call sites, one filter.
+ */
+function visibleSkills(allSkills, offer) {
+    const hidden = new Set(offer?.hiddenIds ?? []);
+    return hidden.size > 0 ? allSkills.filter((s) => !hidden.has(s.id)) : allSkills;
+}
+/**
+ * The visible skills this offer's gate would admit and this description would
+ * LIST — `grantable`, role-filtered, cursor excluded.
+ *
+ * Through `classifySkillTarget`, the same owner the list forty lines below
+ * uses (9.86.0 fix pass). It used to ask a slightly different question — a bare
+ * `grantable.has(s.id)`, which keeps the cursor — so the withhold test and the
+ * list it withholds could disagree about whether there was anything to show: a
+ * cursor that is its own sole grantable id offered the tool and then printed an
+ * empty list under the tree paragraph. Not reachable today (a `tree()` keeps no
+ * cursor, so `cursorId` is undefined on this path), and the point is that it
+ * cannot become reachable — one question, one implementation.
+ */
+function grantableRows(allSkills, offer) {
+    return visibleSkills(allSkills, offer).filter((s) => (0, skillGraph_js_1.classifySkillTarget)({
+        ...(offer.cursorId !== undefined && { cursor: offer.cursorId }),
+        target: s.id,
+        hops: offer.grantable ?? [],
+    }) === 'hop');
+}
+// LENS · tool-description · request-ephemeral
+// reads: the role filter ← `skillToolDescriptors.ts` · visibleSkills, applied FIRST so nothing below can name a hidden skill
+//        grantable ← skillGraph.ts · makeReachableSkills ∪ openSkillIds; class ← skillGraph.ts · classifySkillTarget
+//        named/held ← spoken (src/lib/spokenIds.ts); the cursor ← offer.cursorId, re-checked against hidden
+// the negative sentence is gated on !hopsSpoken.held: a set the filter emptied drops its clause.
+// law: may omit, never deny; every clause anchored to the call it was composed on.
+/**
+ * Compose the tool description: one catalog, or the offer split in two.
+ *
+ * ── THE LENS LAW ──────────────────────────────────────────────────────────
+ *
+ *   A Lens may omit; it may claim absence or refusal only from authoritative
+ *   evidence for the epoch it describes.
+ *
+ * A Lens is anything that shows the model a narrowed view of a wider set. This
+ * function is the framework's sharpest one — it is handed every registered
+ * skill and returns a text that shows some of them — and it is the law's home
+ * because it is the ONE site that does both halves the law governs. It OMITS
+ * (`hiddenIds` removes a skill from the menu, from both columns, and from the
+ * cursor sentence), and it CLAIMS REFUSAL ("read_skill for these will be
+ * refused"). Every other candidate site does one half: `skillRefusal` in the
+ * tool-calls stage only refuses, and it refuses a call that has already been
+ * judged, so its evidence is a verdict rather than a prediction.
+ *
+ * What the two halves cost, and why they are asymmetric:
+ *
+ *   OMISSION is free. A skill this description does not name is a skill the
+ *   model does not consider — no false sentence exists, and a role-hidden
+ *   skill is silently absent rather than declared forbidden, which is the
+ *   whole reason `hiddenIds` omits instead of refusing (naming it would teach
+ *   a role the shape of somebody else's permissions).
+ *
+ *   ABSENCE is a CLAIM, and a claim needs evidence for THIS epoch. So every
+ *   sentence here that could be read as absence is written cursor-relative and
+ *   epoch-scoped: "Not reachable FROM HERE", "Nothing is reachable FROM HERE".
+ *   Never "does not exist", never "you do not have", never "unavailable". The
+ *   difference is not politeness. This description is recomposed for one
+ *   request from that request's own cursor (the `request-ephemeral` argument
+ *   in `test/helpers/modelFacingClaims.ts`), so "from here" is a fact it holds
+ *   evidence for; "does not exist" is a claim about a catalog it was handed a
+ *   filtered view of, and about postures and parks it cannot see. The
+ *   production failure this whole area exists for was exactly that misreading:
+ *   a model read the gate's refusal of its own cursor id as "that skill is
+ *   unavailable" and gave up mid-turn, having never left the skill it was in.
+ *
+ * AND OMISSION IS NOT A SPECIAL CASE OF ABSENCE (9.86.0 fix pass). The law was
+ * stated here and then broken three lines from the bottom: both columns were
+ * computed from a catalog `visibleSkills` had already role-filtered, so "the
+ * graph wires nothing out of here" and "the role may not be told about the one
+ * edge it wires" composed the same sentence — "Nothing is reachable from here"
+ * over a graph holding `alpha → beta`. The hop set is now classified over the
+ * UNFILTERED catalog and put through `spoken`, which keeps `held`: where the
+ * filter is what emptied the column, the clause is dropped and the description
+ * names the cursor and stops. With nothing wired out at all the sentence still
+ * stands, because that absence is one this description has evidence for.
+ *
+ * The known gap is on the record, not hidden: the refusal column is a
+ * compose-time PREDICTION of the gate, and the module header names the two
+ * shipped mechanisms that falsify it in both directions (a `'rails'`/off-menu
+ * `'guard'` posture refuses a hop this list calls reachable; the re-engagement
+ * arm admits a parked member this list calls refusable). Stating a law does not
+ * close a gap — but it does say which sentences the gap is allowed to touch.
+ *
+ * Pinned by `test/core/agent/epoch-laws.test.ts`.
+ */
+function describeOffer(allSkills, line, fullCatalog, offer) {
+    const tail = `Pass the skill's id. The skill's body becomes part of the system prompt and any ` +
+        `gated tools become available on the next call.`;
+    if (!offer) {
+        return `Activate a skill for the next iteration. Available skills:\n${fullCatalog}\n\n${tail}`;
+    }
+    // Hidden first, so nothing below can name one — the menu, the graph split,
+    // the "not reachable" list and the plain catalog all read from this.
+    const hidden = new Set(offer.hiddenIds ?? []);
+    const skills = visibleSkills(allSkills, offer);
+    // One description per id, local to THIS offer. Membership still appears in
+    // every applicable section: relevance is not reachability. Never deduplicate
+    // by description text — distinct skills can legitimately share that text.
+    const described = new Set();
+    const describeOnce = (s) => {
+        if (described.has(s.id))
+            return `  - ${s.id}`;
+        described.add(s.id);
+        return line(s);
+    };
+    // The turn-start MENU leads (SG-C) — rendered from the turn verdict, ids
+    // resolved against the (hidden-filtered) catalog so an id this description
+    // may not name, or one that is not a skill here, is silently skipped rather
+    // than fabricated into a row.
+    const byId = new Map(skills.map((s) => [s.id, s]));
+    const menuRows = (offer.menu?.candidates ?? [])
+        .filter((c) => byId.has(c.id))
+        .map((c) => {
+        const pct = c.relevance !== undefined ? ` (relevance ~${Math.round(c.relevance * 100)}%)` : '';
+        return `${describeOnce(byId.get(c.id))}${pct}`;
+    });
+    // ── THE CURSOR IS NAMED ON EVERY CALL THAT HAS ONE (9.84.0) ─────────
+    // This used to be the STAY clause and nothing else, so it appeared only while
+    // a turn-start menu was outstanding. A turn that routed DECISIVELY has no
+    // menu — and therefore had no sentence anywhere telling the model which skill
+    // it was in. It received a body with no name on it, then read the gate's
+    // refusal of its own id as "that skill is unavailable" and gave up mid-turn.
+    // So the cursor rides the offer whenever it exists, and the stay clause still
+    // rides it when a menu is open.
+    //
+    // ROLE VISIBILITY WINS OVER THE POSITIVE SIGNAL. `hidden` is built above
+    // precisely so nothing below can name a hidden skill, and reading
+    // `offer.cursorId` raw walked past it: a role denied `skill_read` on the
+    // cursor's own skill was still told "You are in 'alpha'" — the one leak the
+    // hidden set exists to prevent, because it teaches a role the name of a
+    // capability no cursor move will ever make available to it. Naming nothing
+    // is the honest fallback: that role loses the positive signal, which is the
+    // price its own policy asked for.
+    const named = offer.cursorId ?? offer.menu?.cursorId;
+    const cursorId = named !== undefined && !hidden.has(named) ? named : undefined;
+    const staying = offer.menu?.stay === true && cursorId !== undefined;
+    // WHAT THE SECOND HALF MAY SAY: outside an outstanding menu, NOTHING.
+    //
+    // Naming the cursor is the whole fix for the production failure this release
+    // exists for — a model that could not tell it was already in a skill read a
+    // refusal as "unavailable" and gave up. Naming it is enough. Every sentence
+    // added ALONGSIDE the name has turned out false somewhere, five rounds
+    // running, and the last one is worth recording because it looked safest of
+    // all: " You do not need read_skill to go on using it." was argued to be a
+    // claim about NECESSITY that no posture, budget or hold-out could falsify.
+    // The PARK falsifies it. A parked map member keeps the cursor and loses its
+    // body and its tools, and `read_skill` is then the only door back — the
+    // re-engagement arm at `toolCalls.ts` exists precisely because 9.59.0 found
+    // that telling a parked model to answer with the current skill made parking
+    // permanent for the rest of the turn. This description cannot see the park
+    // (see the note below on hold-outs), so it cannot know when it would be
+    // lying. So it says the name and stops.
+    //
+    // What it must NOT say is what `read_skill` would DO from here. The deleted
+    // wording ("read_skill MOVES you to a DIFFERENT skill") was that, and it is
+    // false at compose time under two of the three declared postures: `'rails'`
+    // refuses every model hop outright and `'guard'` refuses every hop that is
+    // not on an outstanding menu, so `read_skill` moves nobody — the posture arm
+    // answers a taken-up pick with "read_skill here reaches only the open skills:
+    // …" and contradicts this sentence head-on. Nor is that fixable by making
+    // the sentence posture-aware: the gate's verdict also turns on whether the
+    // pick lands on a menu that is still outstanding, and on whether it is a
+    // parked map member the re-engagement arm admits — facts about a call that
+    // has not happened. A description that predicts the gate can only be a
+    // partial mirror, and a partial mirror is how each of the previous rounds
+    // ended. So it predicts nothing.
+    const cursorLead = cursorId === undefined
+        ? ''
+        : `You are in '${cursorId}'.` +
+            (staying
+                ? ` Staying is a first-class option: answer WITHOUT calling read_skill to ` +
+                    `stay in '${cursorId}'.\n\n`
+                : `\n\n`);
+    // Deliberately no claim about tools here. This description is composed before
+    // the step and park hold-outs filter the wire, so it cannot see what actually
+    // rides; the gate's self-call notice names tools because it reads the merged
+    // list after the fact.
+    const menuLead = offer.menu !== undefined && menuRows.length > 0
+        ? `This turn needs a routing choice. Candidates for this turn ` +
+            `(advisory; use the conversation to choose):\n${menuRows.join('\n')}\n` +
+            (staying
+                ? cursorLead
+                : `Answering WITHOUT calling read_skill is also allowed.\n\n${cursorLead}`)
+        : cursorLead;
+    if (offer.grantable === undefined) {
+        // No graph — the plain catalog, filtered. A role with nothing left is told
+        // plainly rather than handed an empty list to interpret.
+        return skills.length === 0
+            ? `Activate a skill for the next iteration. No skills are available to you — ` +
+                `answer without one, or say what you are unable to do.\n\n${tail}`
+            : `${menuLead}Activate a skill for the next iteration. Available skills:\n${skills
+                .map(describeOnce)
+                .join('\n')}\n\n${tail}`;
+    }
+    // The four target classes, from their ONE owner (9.86.0). `grantable` is the
+    // gate's admitted set (hops ∪ open), so what this description needs from the
+    // classifier is the SELF case: the cursor belongs in neither column, and the
+    // `s.id !== cursorId` check that used to say so lived here, in `toolCalls`,
+    // in `Agent` and in `makeReachableSkills` — four copies of one rule.
+    const classOf = (id) => (0, skillGraph_js_1.classifySkillTarget)({
+        ...(cursorId !== undefined && { cursor: cursorId }),
+        target: id,
+        hops: offer.grantable ?? [],
+    });
+    // ── OMIT, NEVER DENY, ON THE SURFACE THE MODEL CHOOSES FROM ─────────
+    // (9.86.0 fix pass.) `skills` is already role-filtered, so branching on its
+    // length answered "did the role filter empty this?" with the words for "was
+    // the graph holding nothing?" — the identical defect the refusal composer was
+    // repaired for, on the one surface the model actually reads to pick. So the
+    // hop set is classified over the UNFILTERED catalog and put through `spoken`,
+    // which keeps both halves: `named` is what may be listed, `held` is whether
+    // the graph was holding a hop at all. Where the filter is what emptied it,
+    // the negative sentence is omitted rather than printed.
+    const hopRows = allSkills.filter((s) => classOf(s.id) === 'hop');
+    const hopsSpoken = (0, spokenIds_js_1.spoken)(hopRows.map((s) => s.id), (id) => !hidden.has(id));
+    const nameable = new Set(hopsSpoken.named);
+    const open = hopRows.filter((s) => nameable.has(s.id));
+    // ── THE TREE ARM (9.86.0) — a tree has no cursor to move ────────────
+    // `reachableSkills()` is empty from every position under a `tree()`, so the
+    // split above would print "Nothing is reachable from here" and invite a pick
+    // the gate refuses every time. What IS true is named instead: the tree's own
+    // routing, and the open skills a pick can still activate. (With none of
+    // those, `readSkillDescriptor` never gets here — it withholds the tool.)
+    if (offer.treeRouted === true) {
+        return (`${menuLead}Activate a skill for the next iteration. This map is a decision TREE: ` +
+            `it routes by predicate on every iteration and keeps no cursor, so read_skill ` +
+            `cannot move it — a pick of a routed skill is refused. What a pick CAN open are ` +
+            `the skills the tree does not route:\n${open.map(describeOnce).join('\n')}\n\n${tail}`);
+    }
+    // The cursor is never in `grantable` — `makeReachableSkills` filters it out of
+    // its own successor set, because a MOVE to where you already are is not a move.
+    // Listing it under "Not reachable" turned that into a claim about
+    // AVAILABILITY, which is the one thing this list must not say about the skill
+    // the model is standing in. (What this point can and cannot see is settled 30
+    // lines up: the wire is composed AFTER this, so no claim about tools belongs
+    // in either column. The gate's self-call notice is where tools get named,
+    // because it reads the merged list after the fact.) It belongs in neither
+    // column, so it is named once, above, by `cursorLead`.
+    const shut = skills.filter((s) => classOf(s.id) === 'unreachable');
+    const parts = [];
+    if (open.length > 0) {
+        parts.push(`Reachable from here:\n${open.map(describeOnce).join('\n')}`);
+    }
+    else if (!hopsSpoken.held) {
+        // Nothing was wired out of here at all — an absence this description holds
+        // evidence for, cursor-relative and epoch-scoped, so it may be stated.
+        parts.push('Nothing is reachable from here — answer with the skill you are in, or finish.');
+    }
+    if (offer.showRefusable !== false && shut.length > 0) {
+        parts.push(`Not reachable from here (read_skill for these will be refused):\n${shut
+            .map(describeOnce)
+            .join('\n')}`);
+    }
+    // With every clause omitted the description names the cursor and stops, which
+    // is the honest floor: a filtered-away hop is still a hop the graph holds.
+    const body = parts.length > 0 ? `\n\n${parts.join('\n\n')}` : '';
+    return `${menuLead}Activate a skill for the next iteration.${body}\n\n${tail}`;
+}
+// LENS · tool-result · persistent-history
+// reads: nothing — it takes no ReadSkillOffer, so it asks neither visibleSkills (the role filter) nor
+//        classifySkillTarget (position): its execute returns the build-time catalog verbatim
+// known gap: unfiltered and un-cursored on a persistent surface. Reachable through SkillRegistry.toTools()
+// and the doors; the Agent's own auto-attach path mounts read_skill only.
+// law: may omit, never deny; every clause anchored to the call it was composed on.
+/**
+ * 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.
+ */
+function listSkillsDescriptor(skills) {
+    if (skills.length === 0)
+        return undefined;
+    // Capture a stable snapshot — the registry/agent calls this at
+    // build time, so the tool reflects the catalog as of registration.
+    const catalog = skills.map((s) => ({
+        id: s.id,
+        description: s.description ?? '(no description)',
+    }));
+    return {
+        name: 'list_skills',
+        description: 'List all available skills with their ids and descriptions. ' +
+            'Use this to discover what skills exist before calling read_skill.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        execute: () => {
+            // Return as a JSON-serialized string so the LLM can parse easily.
+            return JSON.stringify(catalog, null, 2);
+        },
+    };
+}
+exports.listSkillsDescriptor = listSkillsDescriptor;
+// LENS · tool-description · request-ephemeral
+// reads: the withhold decision ← `grantableRows` → classifySkillTarget, the same owner the list asks
+//        the description ← `describeOffer`
+// known gap, deliberate and pinned (test/security/skill-visibility.test.ts): the `enum: skillIds` on the
+// read_skill schema is built from the UNFILTERED catalog, so a role-hidden id is still named on the wire —
+// the argument is in the comment beginning "The FULL catalog, always" beside it.
+// law: may omit, never deny; every clause anchored to the call it was composed on.
+/**
+ * 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.
+ */
+function readSkillDescriptor(skills, offer) {
+    if (skills.length === 0)
+        return undefined;
+    // ── A TREE WITH NOTHING TO OPEN IS NOT OFFERED (9.86.0) ─────────────
+    // Under a `tree()` every routing pick is refused by construction (the tree
+    // keeps no cursor for read_skill to move), so with no open skill left after
+    // the role filter there is no id this tool could accept. Offering it anyway
+    // is the 8.5.0 defect in its total form: a menu the library knows it will
+    // reject, re-read on every iteration. The NAME stays in the dispatch map, so
+    // a pick made from a restored transcript still reaches the gate's refusal.
+    if (offer?.treeRouted === true && grantableRows(skills, offer).length === 0)
+        return undefined;
+    const skillIds = skills.map((s) => s.id);
+    const line = (s) => `  - ${s.id}: ${s.description ?? '(no description)'}`;
+    const skillCatalog = skills.map(line).join('\n');
+    const byId = new Map();
+    for (const s of skills) {
+        const meta = s.metadata;
+        byId.set(s.id, {
+            body: s.inject.systemPrompt ?? '',
+            surfaceMode: meta?.surfaceMode ?? 'auto',
+        });
+    }
+    return {
+        name: 'read_skill',
+        description: describeOffer(skills, line, skillCatalog, offer),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    // The FULL catalog, always — deliberately NOT narrowed to the reachable
+                    // set (8.5.0). `toolArgValidation` defaults to `'enforce'` and runs BEFORE
+                    // the skill-graph gate, rejecting an off-enum id with a generic schema
+                    // error and `error = true`, which the gate then skips. Narrowing this
+                    // would silently retire the gate's teaching refusal, the
+                    // `agentfootprint.skill.rejected` event, `routeRecorder`'s rejection hops
+                    // and the rejected-cap governor's only input — four honesty mechanisms
+                    // traded for one. The OFFER is narrowed in the description instead, which
+                    // is what the model actually reads to choose.
+                    enum: skillIds,
+                    description: 'The skill id to activate.',
+                },
+            },
+            required: ['id'],
+            additionalProperties: false,
+        },
+        execute: ({ id }) => {
+            const entry = byId.get(id);
+            if (!entry) {
+                return `Unknown skill '${id}'. Available: ${skillIds.join(', ')}`;
+            }
+            // Block C — per-mode tool-result dispatch:
+            //   - 'tool-only' / 'both' → return body verbatim (recency-first
+            //     delivery; LLM sees it as the most recent tool result).
+            //   - 'system-prompt' / 'auto' / unspecified → return confirmation
+            //     only; body lands via system slot on the next iteration.
+            if ((entry.surfaceMode === 'tool-only' || entry.surfaceMode === 'both') && entry.body) {
+                return entry.body;
+            }
+            return skillActivationConfirmation(id);
+        },
+    };
+}
+exports.readSkillDescriptor = readSkillDescriptor;
+// LENS · tool-result · persistent-history
+// reads: only the id it was handed; exported so the gate can tell this sentence from a skill body
+// law: may omit, never deny; every clause anchored to the call it was composed on.
+/**
+ * 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.
+ */
+function skillActivationConfirmation(id) {
+    return `Skill '${id}' activated for the next iteration.`;
+}
+exports.skillActivationConfirmation = skillActivationConfirmation;
+//# sourceMappingURL=skillToolDescriptors.js.map

package/dist/injection-engine/skillToolDescriptors.js.map

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

package/dist/injection-engine/skillTools.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSkipStepTool = exports.buildReadSkillTool = exports.buildListSkillsTool = void 0;
+const tools_js_1 = require("../tools/tools.js");
+const skillSteps_js_1 = require("./skillSteps.js");
+const skillToolDescriptors_js_1 = require("./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.
+ */
+function buildListSkillsTool(skills) {
+    const d = (0, skillToolDescriptors_js_1.listSkillsDescriptor)(skills);
+    if (!d)
+        return undefined;
+    return (0, tools_js_1.defineTool)({
+        name: d.name,
+        description: d.description,
+        inputSchema: d.inputSchema,
+        execute: (args) => d.execute(args),
+    });
+}
+exports.buildListSkillsTool = buildListSkillsTool;
+/**
+ * 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.
+ */
+function buildReadSkillTool(skills, offer) {
+    const d = (0, skillToolDescriptors_js_1.readSkillDescriptor)(skills, offer);
+    if (!d)
+        return undefined;
+    return (0, tools_js_1.defineTool)({
+        name: d.name,
+        description: d.description,
+        inputSchema: d.inputSchema,
+        execute: (args) => d.execute(args),
+    });
+}
+exports.buildReadSkillTool = buildReadSkillTool;
+/**
+ * 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.
+ */
+function buildSkipStepTool() {
+    const d = (0, skillSteps_js_1.skipStepDescriptor)();
+    return (0, tools_js_1.defineTool)({
+        name: d.name,
+        description: d.description,
+        inputSchema: d.inputSchema,
+        execute: (args) => d.execute(args),
+    });
+}
+exports.buildSkipStepTool = buildSkipStepTool;
+//# sourceMappingURL=skillTools.js.map

package/dist/injection-engine/skillTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillTools.js","sourceRoot":"","sources":["../../src/injection-engine/skillTools.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;AAEH,gDAA+C;AAE/C,mDAAqD;AACrD,uEAImC;AAOnC;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CAAC,MAA4B;IAC9D,MAAM,CAAC,GAAG,IAAA,8CAAoB,EAAC,MAAM,CAAC,CAAC;IACvC,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,OAAO,IAAA,qBAAU,EAAgC;QAC/C,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;KACnC,CAAC,CAAC;AACL,CAAC;AATD,kDASC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,kBAAkB,CAChC,MAA4B,EAC5B,KAAsB;IAEtB,MAAM,CAAC,GAAG,IAAA,6CAAmB,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC7C,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,OAAO,IAAA,qBAAU,EAAyB;QACxC,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;KACnC,CAAC,CAAC;AACL,CAAC;AAZD,gDAYC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,iBAAiB;IAC/B,MAAM,CAAC,GAAG,IAAA,kCAAkB,GAAE,CAAC;IAC/B,OAAO,IAAA,qBAAU,EAA6B;QAC5C,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;KACnC,CAAoB,CAAC;AACxB,CAAC;AARD,8CAQC"}

package/dist/injection-engine/skillVocabulary.js.map

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