agentfootprint 10.2.0 → 10.3.1

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

@@ -1,273 +0,0 @@
-/**
- * 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/lib/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/lib/injection-engine/skillPartition.js.map

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

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

@@ -1,228 +0,0 @@
-/**
- * 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/lib/injection-engine/userTurnProducers.test.ts`, which
- * runs the composed sentence through `unprovable`.
- */
-export declare function nudgeTeachingMessage(ptr: StepPointer, plan: StepPlan): string;