agentfootprint 10.2.0 → 10.3.1

package/dist/esm/injection-engine/skillPartition.js

@@ -0,0 +1,273 @@
+/**
+ * skillPartition — three ADVISORY signals about the shape of the partition
+ * itself: how a graph cut the world into skills.
+ *
+ * ## Why the partition is worth a check at all
+ *
+ * Everything else the check-up reports is a wiring fact — an edge to a skill
+ * that is not there, a rule that can never win. The partition is upstream of
+ * all of it, and it is the decision with the most leverage: a graph whose
+ * skills follow SYSTEMS rather than CAPABILITIES makes one ordinary question
+ * cross four skills, and the capability the user actually wanted ends up
+ * implemented outside the graph, by hand, where nothing can see it. Field use
+ * produced exactly that shape — nineteen skills, ONE declared edge, and tool
+ * names carrying the system that owns them (`influx_*`, `pmax_*`, `pstore_*`,
+ * `rvtools_*`) with the skills following the prefixes.
+ *
+ * The important part: all three of those are visible from NAMES AND STRUCTURE
+ * ALONE, at build time, with no run and no model. So the runtime can say them.
+ *
+ * ## Why every one of them is an advisory, and stays one
+ *
+ * Each signal has a legitimate design behind it:
+ *
+ *   • a skill really can be one system's capability (a weather skill wrapping a
+ *     weather API is not a mistake);
+ *   • a deliberately FLAT menu of independent skills really does declare almost
+ *     no edges — a scorer or the model picks, and there is nothing to hand off;
+ *   • a one-call capability really can be one tool with a short body.
+ *
+ * So none of them is ever an error, and none of them says "this is wrong". Each
+ * message states the SIGNAL AS A FACT the author can check against their own
+ * intent — "your 19 skills declare 1 route", "every tool in `powerstore` shares
+ * the prefix `pstore_`" — and then names the design each fact usually indicates
+ * and the design it is also consistent with. This library's check-up teaches;
+ * it does not grade.
+ *
+ * ## The thresholds, and why each one is where it is
+ *
+ * Named constants below, each with the argument beside it. They are chosen so a
+ * SMALL graph is silent (small graphs have no partition problem worth naming),
+ * so a trivially-true observation is never dressed up as a finding (one tool
+ * shares a prefix with itself), and so the commonest honest naming convention —
+ * a VERB first — never fires.
+ *
+ * Zone: PURE CORE. Pinned by
+ * `test/injection-engine/skill-graph-fence.test.ts`.
+ */
+import { skillToolNames } from './skillContract.js';
+/**
+ * How many tools a skill needs before "they all share a prefix" is evidence of
+ * anything. ONE tool shares a prefix with itself — a trivial truth, and the
+ * skill it describes has its own signal below. TWO is two coin flips; a
+ * `get_order` / `get_invoice` pair is a naming habit, not a system boundary.
+ * At THREE the shared prefix is a decision somebody made about scope.
+ */
+const MIN_TOOLS_FOR_PREFIX = 3;
+/**
+ * First segments that are NOT a system — they are the verb half of the house
+ * naming convention (`get_price`, `issue_refund`, `lookup_order`). Verified
+ * against this repo's real tool names, where the ten commonest first segments
+ * are all verbs and outnumber every system prefix put together: without this
+ * list the check would fire on the best-named skills in the library, which is
+ * the fastest way to teach an author to ignore a check-up.
+ *
+ * The test is deliberately crude — a first segment either IS one of these words
+ * or it is not. A cleverer part-of-speech guess would be wrong more quietly.
+ */
+const VERB_PREFIXES = new Set([
+    'get',
+    'set',
+    'put',
+    'post',
+    'add',
+    'read',
+    'write',
+    'list',
+    'find',
+    'fetch',
+    'load',
+    'save',
+    'open',
+    'close',
+    'make',
+    'create',
+    'update',
+    'delete',
+    'remove',
+    'search',
+    'query',
+    'count',
+    'check',
+    'verify',
+    'validate',
+    'run',
+    'exec',
+    'execute',
+    'send',
+    'call',
+    'ask',
+    'show',
+    'lookup',
+    'issue',
+    'approve',
+    'deny',
+    'pay',
+    'process',
+    'resolve',
+    'respond',
+    'inspect',
+    'export',
+    'import',
+    'start',
+    'stop',
+    'cancel',
+    'compute',
+    'calculate',
+    'generate',
+    'summarize',
+    'transform',
+]);
+/**
+ * The floor under ALL THREE signals: below this many skills there is no
+ * partition to have an opinion about.
+ *
+ * This is the module's one structural decision, and it is what keeps the
+ * advisories quiet by construction. Every signal here is a statement about how
+ * a graph CUT THE WORLD; a two-skill graph with no edge is a menu, one skill
+ * wrapping one tool is a choice about that skill, and a pair of tools sharing a
+ * prefix is a naming habit. None of those become a partition question until
+ * there are enough skills for the cut itself to be the design — and the field
+ * case that motivated all three had nineteen. A check that fires on a
+ * three-skill graph teaches an author to stop reading the check-up, which costs
+ * more than the finding is worth.
+ */
+const MIN_SKILLS_FOR_PARTITION = 5;
+/**
+ * The ratio that counts as "almost no declared edges". A graph needs N−1 edges
+ * to connect N skills into one routed structure; this fires below ONE EDGE PER
+ * FOUR SKILLS, which is four times sparser than a bare chain — far enough from
+ * the boundary that a graph tripping it is not a matter of taste. (The field
+ * case: 19 skills, 1 route — a ratio of 0.05.)
+ */
+const MIN_ROUTES_PER_SKILL = 0.25;
+/**
+ * Word count below which a body carries no knowledge the tool schema does not
+ * already carry. One sentence of real guidance — when to reach for this, what
+ * to check first, what the failure looks like — does not fit in 25 words, so a
+ * body under it is either a restatement of the tool's own description or a
+ * placeholder. Counted in whitespace-separated words, the only measure that
+ * means the same thing in prose as in markdown.
+ */
+const THIN_BODY_WORDS = 25;
+/**
+ * Run the three partition signals. Pure, and cheap: one pass over the skills
+ * and two integers. Every problem it produces is a WARNING.
+ */
+export function checkPartition(input) {
+    const skillCount = input.skills.length;
+    // The floor, applied once for all three signals — see
+    // MIN_SKILLS_FOR_PARTITION. A small graph reports byte-identically to the
+    // way it did before this module existed.
+    if (skillCount < MIN_SKILLS_FOR_PARTITION)
+        return [];
+    const problems = [];
+    for (const skill of input.skills) {
+        const tools = skillToolNames(skill);
+        const id = idOf(skill);
+        // 1. tools-share-prefix — every tool in the skill comes from one system.
+        //    Computed from the first `_`-delimited segment, which is where a system
+        //    prefix lives when there is one (`pstore_list_volumes` → `pstore`), and
+        //    silent when that segment is a verb (see VERB_PREFIXES).
+        const prefix = sharedPrefix(tools);
+        if (tools.length >= MIN_TOOLS_FOR_PREFIX && prefix !== undefined) {
+            problems.push({
+                kind: 'warning',
+                code: 'tools-share-prefix',
+                message: `Every tool in "${id}" shares the prefix \`${prefix}_\` (${tools.join(', ')}). ` +
+                    `A skill whose whole tool set comes from one system is usually a wrapper around ` +
+                    `that SYSTEM rather than a CAPABILITY — and when the skills follow the systems, one ` +
+                    `ordinary question crosses several of them, so the thing the user actually asked ` +
+                    `for gets built outside the graph where nothing can route it. Worth checking: ` +
+                    `could a user's question be answered by "${id}" alone, or does answering it need ` +
+                    `two of these skills at once? If it needs two, the capability is the skill and ` +
+                    `\`${prefix}_\` is just where its tools happen to come from. If "${id}" really is ` +
+                    `one system's capability, this is exactly right and there is nothing to fix.`,
+                skill: id,
+            });
+        }
+        // 2. skill-wraps-one-tool — one tool, and a body that adds nothing to its
+        //    schema. The body is what the model reads to decide HOW to use the
+        //    tool; when it is this short there is no procedure in the graph, only
+        //    an endpoint with a name.
+        if (tools.length === 1 && tools[0] !== undefined) {
+            const words = wordCount(bodyOf(skill));
+            if (words < THIN_BODY_WORDS) {
+                problems.push({
+                    kind: 'warning',
+                    code: 'skill-wraps-one-tool',
+                    message: `Skill "${id}" carries one tool (\`${tools[0]}\`) and a ${words}-word body — ` +
+                        `under the ${THIN_BODY_WORDS} words it takes to say when to reach for it, what to ` +
+                        `check first, or what a bad answer looks like. A skill whose body adds nothing to ` +
+                        `the tool's own schema is an endpoint wrapper: the model already sees the tool, so ` +
+                        `the skill buys nothing but a name and an activation. Either put the knowledge in ` +
+                        `the body (that is the half a schema cannot carry), or drop the skill and register ` +
+                        `\`${tools[0]}\` on the agent directly. If it is genuinely a one-call capability ` +
+                        `with nothing to say about it, registering the tool is the smaller thing.`,
+                    skill: id,
+                });
+            }
+        }
+    }
+    // 3. few-declared-edges — many skills, almost no declared handoffs. A graph
+    //    level fact, reported once, and never for a tree (a tree declares its
+    //    routing as the tree).
+    if (!input.isTree && input.routeCount < skillCount * MIN_ROUTES_PER_SKILL) {
+        problems.push({
+            kind: 'warning',
+            code: 'few-declared-edges',
+            message: `This graph declares ${plural(skillCount, 'skill', 'skills')}, ${plural(input.entryCount, 'entry', 'entries')} and ${plural(input.routeCount, 'route', 'routes')} — fewer than one route per four ` +
+                `skills, where connecting ${skillCount} skills into one routed structure takes at ` +
+                `least ${skillCount - 1}. When skills hand off to each other in PROSE ("then use the ` +
+                `capacity skill"), the handoff is invisible: nothing draws it, \`checkup()\` cannot ` +
+                `check it, the reachability walk cannot see it, and \`read_skill\`'s gate cannot ` +
+                `offer it — the model is left to infer the sequence every turn. Declaring the ones ` +
+                `you already rely on (\`.route(a, b, { onToolReturn })\`) turns each into something ` +
+                `the graph can route and a reader can see. If this is a deliberately flat menu of ` +
+                `independent skills — a scorer or the model picks one and it answers alone — then ` +
+                `there is nothing to hand off and this is the shape you meant.`,
+        });
+    }
+    return problems;
+}
+/** The id, read structurally like every other check in this family. */
+function idOf(skill) {
+    return skill.id;
+}
+/** The skill's BODY — the prose that lands in the system slot when it
+ *  activates. Same accessor `skillContract.ts` reads. */
+function bodyOf(skill) {
+    return skill.inject?.systemPrompt ?? '';
+}
+function wordCount(text) {
+    const trimmed = text.trim();
+    return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
+}
+/**
+ * The first `_`-delimited segment shared by EVERY name, or undefined when there
+ * is none, when a name carries no `_` at all, or when the shared segment is a
+ * verb (a convention, not a system — see {@link VERB_PREFIXES}).
+ *
+ * Case-folded, because a tool registry that mixes `PSTORE_get` and
+ * `pstore_list` is still one system.
+ */
+function sharedPrefix(names) {
+    if (names.length === 0)
+        return undefined;
+    let shared;
+    for (const name of names) {
+        const separator = name.indexOf('_');
+        if (separator <= 0)
+            return undefined; // no prefix segment to speak of
+        const segment = name.slice(0, separator).toLowerCase();
+        if (shared === undefined)
+            shared = segment;
+        else if (shared !== segment)
+            return undefined;
+    }
+    return shared !== undefined && !VERB_PREFIXES.has(shared) ? shared : undefined;
+}
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+//# sourceMappingURL=skillPartition.js.map

package/dist/esm/injection-engine/skillPartition.js.map

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

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

@@ -0,0 +1,228 @@
+/**
+ * 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;