@wrongstack/core 0.299.0 → 0.301.0

package/dist/core/instruction-template.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Conditional templating for the file-backed instruction layers.
+ *
+ * Why this exists: `instructions/system.md` (and its `-lite` / `-pro`
+ * variants) used to be injected as layer-1 verbatim, listing ~100 tool names
+ * regardless of which tools the current request actually exposed. At
+ * `minimal`/`light` tier only the 15 TIER1 tools are sent directly
+ * (`@wrongstack/tools` `selectBuiltinToolsForTier`), yet the prompt still
+ * spent ~8k tokens explaining `kanban`, the browser tools, the SAGE memory
+ * tools and the Telegram bridge. Those tools may remain executable through
+ * lazy discovery, but are not legal direct calls in that request. The
+ * token-saving tier was spending most of its savings back in the prompt, and
+ * the text had to carry a "some of the above may be a lie" disclaimer to
+ * compensate.
+ *
+ * Layer-2 (`buildToolUsage`) already gated its guidance on the live tool set;
+ * this module gives the markdown layers the same power without splitting the
+ * files apart, so project/profile overrides keep working and the sources stay
+ * readable.
+ *
+ * ## Syntax
+ *
+ * Block form — HTML comments, invisible in a markdown preview:
+ *
+ * ```markdown
+ * <!--ws:if tool=kanban-->
+ * ## Work planning with Kanban
+ * ...
+ * <!--ws:else-->
+ * Track multi-step work with `todo`.
+ * <!--ws:end-->
+ * ```
+ *
+ * Conditions are space-separated attributes, ANDed together. Values within one
+ * attribute are comma-separated and ORed. A leading `!` negates the attribute.
+ *
+ * - `tool=a,b,c` — at least one of those tools is registered
+ * - `!tool=a,b`  — none of those tools is registered
+ * - `tier=off,medium` — the active token-saving tier is one of these
+ * - `role=leader` / `role=subagent`
+ *
+ * Inline form, for tool inventory lines:
+ *
+ * ```markdown
+ * {{tools:read,edit,write,patch}}
+ * ```
+ *
+ * renders only the registered names, backticked and comma-joined; it renders
+ * as the empty string when none are registered.
+ *
+ * ## Fail-open contract
+ *
+ * A malformed override must never blank the identity prompt, so every error
+ * path keeps text and drops only the marker:
+ *
+ * - unknown attribute / malformed condition → the condition is treated as true
+ * - stray `ws:else` / `ws:end` → the marker is dropped, surrounding text stays
+ * - unclosed `ws:if` at EOF → every branch's content is emitted in source order
+ * - no context passed → every condition is true (the "all tools present" view)
+ *
+ * @module core/instruction-template
+ */
+import type { ConcreteTokenSavingTier } from '../types/config.js';
+export interface InstructionTemplateContext {
+    /** Names of the tools registered for the current request. */
+    toolNames: ReadonlySet<string>;
+    /** Effective token-saving tier, as resolved by the system prompt builder. */
+    tier: ConcreteTokenSavingTier;
+    /** True when building a subagent prompt (`role=subagent`). */
+    subagent: boolean;
+    /** Values for plain `{{name}}` placeholders. Unknown names are left as-is. */
+    vars?: Record<string, string | number> | undefined;
+    /** Drop lines that format a declared but unavailable tool as callable. */
+    strictToolReferences?: boolean | undefined;
+}
+/**
+ * Render an instruction markdown layer against the live request.
+ *
+ * Passing no context strips every marker and keeps the full text, which is the
+ * right view for embedders reading the bundled prompt directly.
+ */
+export declare function renderInstructionLayer(text: string, ctx?: InstructionTemplateContext | undefined): string;
+//# sourceMappingURL=instruction-template.d.ts.map

package/dist/core/next-steps-slot.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Turn-scoped slot for `<nextsteps>` suggestions produced by the `nextsteps`
+ * tool, plus the renderer that turns them back into the canonical XML block.
+ *
+ * ## Why a slot and not a direct channel to the UI
+ *
+ * Every suggestion surface — the TUI history renderer, the WebUI and SimpleUI
+ * chat stores, the CLI REPL suggestion store, and the session replay/rehydrate
+ * paths — reads `<nextsteps>` out of the assistant's *message text* via
+ * `parseNextSteps` in `@wrongstack/tools/next-steps`. Handing the tool its own
+ * transport would mean teaching all of them a second source of truth, and any
+ * one of them lagging behind would silently drop suggestions.
+ *
+ * Instead the tool parks its steps here, and `maybeAppendPendingNextSteps`
+ * appends the rendered block to the turn-ending provider response before that
+ * response is emitted, persisted, or folded into `finalText`. Downstream code
+ * cannot tell the difference between a block the model typed and one the tool
+ * produced, which is exactly the point.
+ *
+ * ## Why this module duplicates the tag knowledge
+ *
+ * `core` sits below `tools` in the package DAG (enforced by
+ * `package-boundaries.test.ts`), so it cannot import the parser. The overlap is
+ * deliberately kept to the tag name and the item line shape; the round-trip
+ * test in `tests/next-steps-slot.test.ts` feeds this renderer's output through
+ * the real parser so the two cannot drift apart unnoticed.
+ */
+import type { Response } from '../types/provider.js';
+import type { Context } from './context.js';
+/** A single suggestion parked by the `nextsteps` tool. */
+export interface PendingNextStep {
+    text: string;
+    /** Opt-in unattended execution. Honored only on the first item. */
+    auto?: boolean | undefined;
+}
+/**
+ * Upper bound on parked steps. The parser accepts up to 6, but the leader
+ * prompt's contract is 1–4, so the slot enforces the tighter number and the
+ * tool's schema mirrors it.
+ */
+export declare const MAX_PENDING_NEXT_STEPS = 4;
+/**
+ * Park the steps for this turn, replacing anything already there.
+ *
+ * Replace (rather than append) matches `todo`'s whole-list semantics: a second
+ * call in the same turn is the model changing its mind, not adding to a list.
+ */
+export declare function writePendingNextSteps(ctx: Pick<Context, 'meta'>, steps: readonly PendingNextStep[]): void;
+/** Read the parked steps, or undefined when the slot is empty or malformed. */
+export declare function readPendingNextSteps(ctx: Pick<Context, 'meta'>): PendingNextStep[] | undefined;
+/**
+ * Empty the slot. Called at the start of every `run()` so a block produced for
+ * one prompt can never attach itself to the answer for the next one, and again
+ * after a successful append so it cannot repeat within the same run.
+ */
+export declare function clearPendingNextSteps(ctx: Pick<Context, 'meta'>): void;
+/** True when the text already carries a `<nextsteps>` block the model wrote. */
+export declare function hasNextStepsTag(text: string): boolean;
+/**
+ * Render parked steps as the canonical block.
+ *
+ * The output must satisfy `parseNextSteps` exactly: an opening tag with no
+ * attributes, one `N. text` line per item, `auto="true"` only ever on item 1,
+ * and a balanced closing tag.
+ */
+export declare function renderNextStepsBlock(steps: readonly PendingNextStep[]): string;
+/**
+ * Append the parked `<nextsteps>` block to the turn-ending response.
+ *
+ * Returns `res` untouched unless every gate passes:
+ *
+ * - **leader only** — subagent output is parsed or rolled up by its parent, so
+ *   a suggestion block there is noise that leaks into specs and plans. Same
+ *   check as `buildLiveNextStepsGateBlock`.
+ * - **turn-ending stop reason** — mid-turn prose must not surface suggestions;
+ *   every surface gates on this already.
+ * - **not aborted** — an interrupted turn has no answer to follow up on.
+ * - **no open todos** — finishing tracked work outranks proposing new work.
+ *   Enforced here rather than per-surface so the gate has one home.
+ * - **no block already in the text** — if the model also typed one, its own
+ *   wording is the fresher intent and wins.
+ *
+ * The block is *appended* to the last text block, never prepended: the WebUI
+ * only accepts a canonical-response update when it extends the text it already
+ * streamed (`session-handlers.ts`), so a prefix would be silently dropped.
+ */
+export declare function maybeAppendPendingNextSteps(ctx: Pick<Context, 'meta' | 'agentId' | 'todos' | 'signal'>, res: Response): Response;
+//# sourceMappingURL=next-steps-slot.d.ts.map

package/dist/core/system-prompt-blocks.d.ts

@@ -12,6 +12,7 @@ import type { MailboxAgentStatus } from '../coordination/mailbox-types.js';
 import type { TextBlock } from '../types/blocks.js';
 import type { Tool } from '../types/tool.js';
 import type { InstructionBundle } from './instruction-bundle.js';
+import { type InstructionTemplateContext } from './instruction-template.js';
 /**
  * The section of the system prompt a given TextBlock originated from. Used by
  * `getContextBreakdown()` to attribute real token counts per category in the
@@ -30,7 +31,15 @@ export declare const SYSTEM_BLOCK_SOURCE: WeakMap<TextBlock, SystemBlockSource>;
 /** Tag a freshly-built block with its origin, returning the same reference. */
 export declare function tagBlock(block: TextBlock, source: SystemBlockSource): TextBlock;
 export declare function shortSessionId(sessionId: string): string;
-export declare function instructionSection(bundle: InstructionBundle, key: string, vars?: Record<string, string | number>): string;
+/**
+ * Render one `sections/*.md` entry.
+ *
+ * `tplCtx` opts the section into the same conditional-block syntax the identity
+ * layers use (see `instruction-template.ts`); without it the section is
+ * rendered with every condition true, which matches the pre-templating
+ * behaviour for callers that don't have a live tool set to hand.
+ */
+export declare function instructionSection(bundle: InstructionBundle, key: string, vars?: Record<string, string | number>, tplCtx?: InstructionTemplateContext | undefined): string;
 export declare function renderToolSelectionBoundary(tool: Tool): string;
 /**
  * Cheap content fingerprint of the online agents array. The mailbox

package/dist/core/system-prompt-builder.d.ts

@@ -6,7 +6,8 @@ import type { SkillLoader } from '../types/skill.js';
 import type { BuildContext, ModelCapabilities, SystemPromptBuilder, SystemPromptRegions } from '../types/system-prompt.js';
 import type { SystemPromptContributor } from '../types/system-prompt-contributor.js';
 import { type InstructionBundle, type InstructionBundlePaths } from './instruction-bundle.js';
-export { effectiveShell, shellGuidanceBlock, type EffectiveShell } from './system-prompt-shell.js';
+import { type InstructionTemplateContext } from './instruction-template.js';
+export { type EffectiveShell, effectiveShell, shellGuidanceBlock } from './system-prompt-shell.js';
 export declare const LAYER_1_IDENTITY: string;
 /**
  * Compose the layer-1 identity from the bundled default plus any override.
@@ -20,8 +21,16 @@ export declare const LAYER_1_IDENTITY: string;
  *
  * Bundled, profile-global and explicitly-passed override files are user-owned
  * and keep full replacement semantics.
+ *
+ * `tplCtx` renders the conditional blocks in the markdown against the live tool
+ * set (see `instruction-template.ts`), so guidance for tools the current
+ * request never registered stays out of the prompt entirely. The two layers are
+ * rendered **separately** rather than after concatenation: an unclosed
+ * `ws:if` in the repo-committed file must not be able to swallow the genuine
+ * identity that precedes it. Omitting `tplCtx` keeps the full text, which is
+ * what embedders reading the bundled prompt directly expect.
  */
-export declare function buildIdentityLayer(identity: string | undefined, source: 'bundled' | 'global' | 'project' | 'file' | undefined): string;
+export declare function buildIdentityLayer(identity: string | undefined, source: 'bundled' | 'global' | 'project' | 'file' | undefined, tplCtx?: InstructionTemplateContext | undefined): string;
 export type { SystemBlockSource } from './system-prompt-blocks.js';
 export { SYSTEM_BLOCK_SOURCE } from './system-prompt-blocks.js';
 export interface DefaultSystemPromptBuilderOptions {
@@ -36,8 +45,8 @@ export interface DefaultSystemPromptBuilderOptions {
     injectMemory?: boolean | undefined;
     skillLoader?: SkillLoader | undefined;
     /**
-     * How skill bodies reach the prompt. `'eager'` (default) injects every
-     * discovered skill body; `'progressive'` injects only a name+trigger manifest
+     * How skill bodies reach the prompt. `'progressive'` (runtime default)
+     * injects only a name+trigger manifest; `'eager'` injects discovered bodies
      * and relies on the agent calling the `skill` tool to load a body on demand
      * (the agentskills.io progressive-disclosure model).
      */
@@ -122,11 +131,20 @@ export declare class DefaultSystemPromptBuilder implements SystemPromptBuilder {
     private skillBodyCache?;
     /** Tools from last build — used for memory relevance scoring. */
     private _lastBuildTools?;
+    /** Full executable catalog used to capability-gate progressive skills. */
+    private _lastCatalogTools?;
     /** Cached rendered online agents string, keyed by content fingerprint. */
     private _lastOnlineAgents?;
     /** Cached full buildToolUsage output — keyed by tools array ref + agents fingerprint + tier. */
     private _toolsUsageCache?;
     private _instructionBundle?;
+    /**
+     * Cached rendered identity layer. Keyed the same way as `_toolsUsageCache`:
+     * the ToolRegistry snapshot keeps the array reference stable until a registry
+     * mutation, so reference equality is a sound key for "the tool set did not
+     * change".
+     */
+    private _identityCache?;
     constructor(opts?: DefaultSystemPromptBuilderOptions);
     /**
      * Normalizes `tokenSavingMode` to a boolean for backward-compatible boolean checks.
@@ -152,6 +170,24 @@ export declare class DefaultSystemPromptBuilder implements SystemPromptBuilder {
     private toolDescLimit;
     build(ctx: BuildContext): Promise<TextBlock[]>;
     buildRegions(ctx: BuildContext): Promise<SystemPromptRegions>;
+    /**
+     * The view of the live request that the markdown conditionals are evaluated
+     * against: which tools can actually be called, the effective token-saving
+     * tier, and whether this prompt is for a subagent.
+     */
+    private templateContext;
+    /**
+     * Render the identity layer, memoized on the tool set / tier / role triple.
+     *
+     * The rendering itself is a couple of regex passes over ~40 KB, which is
+     * cheap but happens on every turn; the tool set is stable for the life of a
+     * session in the normal case, so the cache turns it into a one-off.
+     *
+     * This does not cost prompt-cache hits: in the wire format the `tools` array
+     * precedes `system`, so any registry mutation already invalidates the
+     * provider's prefix cache before the identity block is reached.
+     */
+    private buildIdentity;
     private instructions;
     /**
      * Cached plan content keyed by (planPath, mtimeMs). The plan is read

package/dist/core/system-prompt-memory-skills.d.ts

@@ -46,6 +46,7 @@ export interface MemorySkillsContext {
     skillEagerMaxChars: number | undefined;
     /** Tools from the last build — used for memory relevance scoring. */
     lastBuildTools: Tool[] | undefined;
+    catalogTools: Tool[] | undefined;
     skillBodyCache: string | undefined;
 }
 /**

package/dist/core/system-prompt-skill-bodies.d.ts

@@ -1,5 +1,5 @@
 import type { SkillLoader } from '../types/skill.js';
-export declare function buildProgressiveSkillManifestText(loader: SkillLoader): Promise<string>;
-export declare function buildFullSkillBodiesText(loader: SkillLoader, budget?: number): Promise<string>;
-export declare function buildCompactSkillBodiesText(loader: SkillLoader, budget?: number): Promise<string>;
+export declare function buildProgressiveSkillManifestText(loader: SkillLoader, availableToolNames?: readonly string[]): Promise<string>;
+export declare function buildFullSkillBodiesText(loader: SkillLoader, budget?: number, availableToolNames?: readonly string[]): Promise<string>;
+export declare function buildCompactSkillBodiesText(loader: SkillLoader, budget?: number, availableToolNames?: readonly string[]): Promise<string>;
 //# sourceMappingURL=system-prompt-skill-bodies.d.ts.map