@hasna/skills 0.10.83 → 0.10.89

package/dist/lib/session-background-renewal.d.ts

@@ -0,0 +1,118 @@
+import { SkillSelectionError, type SelectionCacheOptions } from "./selection-cache.js";
+import { type SessionReconciliationOptions } from "./session-reconciliation.js";
+/** The longest an expired-pin prompt waits for its background renewal. */
+export declare const BACKGROUND_RENEWAL_WAIT_MS = 3000;
+/** A lock older than this belongs to no live worker (the worker's own budget plus margin). */
+export declare const BACKGROUND_RENEWAL_LOCK_TTL_MS: number;
+/** A failed attempt for the same pin is reported again, not retried, within these windows. */
+export declare const EXPIRED_RENEWAL_RETRY_MS = 30000;
+export declare const AHEAD_RENEWAL_RETRY_MS: number;
+export type BackgroundRenewalMode = "expired" | "ahead";
+export type BackgroundRenewalStatus = "running" | "renewed" | "migrated" | "unchanged" | "failed";
+export interface BackgroundRenewalState {
+    schemaVersion: 1;
+    kind: "session-pin-background-renewal";
+    sessionId: string;
+    profileId: string;
+    operationId: string;
+    /** verifiedAt of the exact pin this attempt renews. */
+    pinVerifiedAt: string;
+    mode: BackgroundRenewalMode;
+    status: BackgroundRenewalStatus;
+    startedAt: string;
+    finishedAt?: string;
+    workerPid?: number;
+    code?: string;
+    migrationTimeout?: true;
+    /** No worker could be started; such a record never delays the next attempt. */
+    notStarted?: true;
+    /**
+     * The exact request this attempt answers: the receipt bytes, mode,
+     * migration setting and prompt directory. A recorded failure is reused only
+     * for the same request; any change (a rewritten receipt, migration turned
+     * on, another directory) asks again at once.
+     */
+    requestDigest?: string;
+}
+export interface BackgroundRenewalRequest {
+    sessionId: string;
+    profileId: string;
+    pinVerifiedAt: string;
+    mode: BackgroundRenewalMode;
+    /** SHA-256 of the exact receipt bytes this request read. */
+    receiptSha256: string;
+    /** Expired pins only: the managed hook's automatic migration of a refused renewal. */
+    migrate?: boolean;
+    /** The prompt's directory, which migration requires (project locks keep the refusal). */
+    projectDir?: string;
+}
+export interface BackgroundRenewalOptions extends SelectionCacheOptions {
+    /**
+     * Tests replace the detached worker; production spawns `skills sessions
+     * renew-background`. `notStarted` is called if the worker fails to start
+     * after this returns (an asynchronous spawn error such as EAGAIN).
+     */
+    spawnWorker?: (args: string[], notStarted: () => void) => void;
+}
+/** The identity of one renewal request; equal digests ask the authority the same question. */
+export declare function backgroundRenewalRequestDigest(request: BackgroundRenewalRequest): string;
+/**
+ * The last recorded attempt for this session, or null when absent or not
+ * exact. Only validated fields are returned; anything else in the file is
+ * dropped, so no unvalidated value reaches a caller's output.
+ */
+export declare function readBackgroundRenewalState(sessionId: string, options?: SelectionCacheOptions): BackgroundRenewalState | null;
+export type BackgroundRenewalStart = 
+/** `operationId` names the attempt to wait for, when its lock is readable. */
+{
+    status: "started" | "running";
+    operationId?: string;
+}
+/** `notStarted`: no worker could be started, so the caller may renew inline instead. */
+ | {
+    status: "failed";
+    state: BackgroundRenewalState;
+    notStarted?: true;
+};
+/**
+ * Start the session's background renewal unless one is running, or report a
+ * recent failure of the same pin without starting another.
+ */
+export declare function startBackgroundRenewal(request: BackgroundRenewalRequest, options?: BackgroundRenewalOptions): BackgroundRenewalStart;
+export type BackgroundRenewalWait = {
+    status: "running" | "changed";
+} | {
+    status: Exclude<BackgroundRenewalStatus, "running">;
+    state: BackgroundRenewalState;
+};
+/**
+ * Wait up to waitMs for the attempt renewing this exact pin to finish, or for
+ * the session receipt to stop holding that pin. With an operation id, only
+ * that attempt's outcome counts.
+ */
+export declare function awaitBackgroundRenewal(sessionId: string, pinVerifiedAt: string, waitMs: number, options?: SelectionCacheOptions, operationId?: string): Promise<BackgroundRenewalWait>;
+export interface BackgroundRenewalRun {
+    status: BackgroundRenewalStatus | "superseded";
+    code?: string;
+}
+/**
+ * The worker: renew (or, for an expired pin with migration on, migrate) one
+ * session pin with the background budget, record the outcome, release the lock.
+ */
+export declare function runBackgroundRenewal(sessionId: string, profileId: string, operationId: string, request: {
+    migrate?: boolean;
+    projectDir?: string;
+}, options?: SessionReconciliationOptions): Promise<BackgroundRenewalRun>;
+/**
+ * An expired pin whose background renewal is still running. It keeps the
+ * renewal timeout's code (fixed codes cross the hook boundary) and a fixed
+ * marker so the hook can say the renewal continues instead of restarting.
+ */
+export declare class SessionRenewalInBackground extends SkillSelectionError {
+    readonly renewal: "background";
+    constructor();
+}
+/** The recorded failure of a background attempt, as the error the inline renewal would have raised. */
+export declare function backgroundRenewalError(state: BackgroundRenewalState): SkillSelectionError;
+/** The pin's age class, from its verifiedAt; null when it is neither due nor expired. */
+export declare function renewalModeFor(verifiedAt: string, now: number): BackgroundRenewalMode | null;

package/dist/lib/session-reconciliation.d.ts

@@ -49,8 +49,71 @@ export declare function inspectSkillSession(sessionId: string, options?: Selecti
         bundleDigest: string;
     }[];
 };
-/** Fits inside the managed context child's 6.5-second ceiling, including CLI work. */
-export declare const SESSION_RENEWAL_TIMEOUT_MS = 4000;
+/** The managed user-prompt hook's own deadline, measured from hook start. */
+export declare const MANAGED_HOOK_DEADLINE_MS = 12000;
+/**
+ * The managed context child's own ceiling. It stays above
+ * SESSION_RENEWAL_TIMEOUT_MS so the parent never kills a renewal that is still
+ * inside its own budget, and below MANAGED_HOOK_DEADLINE_MS.
+ */
+export declare const SESSION_CONTEXT_CHILD_CEILING_MS = 11000;
+/**
+ * Kept by the managed hook after its context child's limit: the hook's own
+ * startup before it set its deadline (an outer supervisor's timer was already
+ * running) and writing its diagnostic, so the hook reports before it is killed.
+ */
+export declare const MANAGED_HOOK_EXIT_RESERVE_MS = 1000;
+/**
+ * Kept by the context child around its renewal: its own startup before the
+ * renewal deadline starts and writing its result. A renewal at a 9 s budget
+ * measured about 9.25 s of child time in cli.session-renewal-budget.test.ts.
+ */
+export declare const SESSION_CONTEXT_CHILD_RESERVE_MS = 1000;
+/**
+ * SessionStart refreshes the station profile before its context. That
+ * refresh is bounded so it cannot use the window verified context needs: it
+ * ends by this budget, and always leaves SESSION_START_CONTEXT_RESERVE_MS of
+ * the hook's window (the context child's startup, a background renewal's
+ * bounded wait and the hook's report). A refresh that times out or cannot
+ * reach the authority is reported in one line, and the session uses its last
+ * verified profile within the usual 24-hour bound.
+ */
+export declare const SESSION_START_SYNC_BUDGET_MS = 5000;
+export declare const SESSION_START_CONTEXT_RESERVE_MS = 6000;
+export declare function sessionStartSyncBudget(remainingMs: number): number;
+/**
+ * Limits for one managed context child, from the time the hook has left. On a
+ * full prompt window the renewal keeps its whole budget; after a lifecycle
+ * sync has used part of the window, the renewal shrinks first, so each layer
+ * times out inside the one that encloses it and reports its own code.
+ */
+export declare function managedContextChildLimits(remainingMs: number): {
+    childMs: number;
+    renewalBudgetMs: number;
+};
+/**
+ * Renewal budget for one managed-hook prompt. A renewal re-reads every changed
+ * pinned selection at SESSION_RENEWAL_CONCURRENCY, so this has to cover the
+ * profile's real churn and not just the profile read. Measured on the live
+ * 831-selection profile with a pin carrying 807 selections, 85 of them changed:
+ * the exact-version reads alone took ~6.1 s cold and ~4.6 s warm, before the
+ * client, the two profile resolves and the receipt write. A 4-second budget sat
+ * inside that range, so one pin renewed or timed out on authority latency alone.
+ */
+export declare const SESSION_RENEWAL_TIMEOUT_MS = 9000;
+/**
+ * Budget of one background renewal (`skills sessions renew-background`),
+ * which managed hooks start instead of renewing on the prompt's critical
+ * path. It covers a large pin's historical reads on a slow authority; the
+ * authorization checks are the inline renewal's own.
+ */
+export declare const BACKGROUND_SESSION_RENEWAL_BUDGET_MS = 120000;
+/**
+ * A root session's pin is renewed ahead of expiry once it is this old, while
+ * it is still valid, so an active session normally never reaches expiry and
+ * its prompts keep receiving context from the valid pin meanwhile.
+ */
+export declare const SESSION_RENEW_AHEAD_AGE_MS: number;
 /**
  * A definitive automatic renewal refusal is remembered briefly so the managed
  * hook does not resolve the whole profile again on every prompt. The record
@@ -112,6 +175,23 @@ export interface SessionPinRenewalOptions extends SessionReconciliationOptions {
      * does not run.
      */
     projectDir?: string;
+    /**
+     * Managed hooks only: the time the caller has left for this renewal. The
+     * renewal uses the smaller of this and SESSION_RENEWAL_TIMEOUT_MS, so it
+     * reports its own SESSION_RENEWAL_TIMEOUT before an outer layer kills it.
+     */
+    budgetMs?: number;
+    /**
+     * Background renewal only: the budget ceiling is
+     * BACKGROUND_SESSION_RENEWAL_BUDGET_MS instead of SESSION_RENEWAL_TIMEOUT_MS.
+     */
+    background?: boolean;
+    /**
+     * Renew once the pin is at least this old (default: only after it expired).
+     * Background renew-ahead passes SESSION_RENEW_AHEAD_AGE_MS. The renewal
+     * itself and every check it makes are unchanged; only when it may start is.
+     */
+    renewAfterMs?: number;
 }
 /**
  * A refused renewal whose automatic migration could not finish within the

package/dist/lib/skill-context.d.ts

@@ -1,5 +1,5 @@
 import type { ResolvedSkillSelection } from "../types/skill-selection.js";
-import { type SelectionResolverOptions } from "./selection-resolver.js";
+import { type ResolvedSelectionContext, type SelectionResolverOptions } from "./selection-resolver.js";
 export interface SkillContextInput {
     prompt?: string;
     cwd?: string;
@@ -15,6 +15,25 @@ export interface SkillContextInput {
 export interface SkillContextOptions extends SelectionResolverOptions {
     maxChars?: number;
     maxSkills?: number;
+    /**
+     * An unnamed prompt match whose longest matched phrase has fewer words than
+     * this is offered as a load command instead of being injected, however many
+     * such words matched. Named, explicit, path and required selections are not
+     * affected. Unset, every counted match may be injected.
+     */
+    minPromptPhraseWords?: number;
+    /** Print load pointers with --cache-first even though this context didn't come from the cache: a managed hook that fell back to the service. */
+    pointerCacheFirst?: boolean;
+    /** Bodies a child session receives from its parent's loaded skills; the rest are offered. Unset, HISTORY_BODY_LIMITS applies. */
+    inheritedBodies?: number;
+    /** Called with the resolved pin before any payload is read (again if a new child is resolved again); metadata only. */
+    onResolved?: (resolved: ResolvedSelectionContext) => void;
+    /**
+     * performance.now() time after which a new child whose parent receipt
+     * changed while it resolved is not resolved again (the managed hook passes
+     * its renewal deadline). Without it the single retry is unconditional.
+     */
+    resolveAgainBefore?: number;
 }
 export interface ContextSelectionReceipt extends ResolvedSkillSelection {
     reason: string;
@@ -42,4 +61,34 @@ export interface SkillContextResult {
         selections: ContextSelectionReceipt[];
     };
 }
+/**
+ * Re-delivered history (a subagent's inheritance and a restore after
+ * compaction or resume) carries no prompt, so its relevance is recency: the
+ * most recently loaded skills first, a few bodies, then load commands. Older
+ * history stays loadable with `skills load` and is not re-listed.
+ */
+export declare const HISTORY_BODY_LIMITS: Readonly<Record<"subagent-inherit" | "session-restore", number>>;
+export declare const HISTORY_CANDIDATE_LIMIT = 10;
+/**
+ * The one fixed line that says a context was limited because this session's
+ * record could not be updated: newly read skills are offered as load commands
+ * instead of being delivered unrecorded.
+ */
+export declare const SESSION_WRITE_BUSY_NOTICE = "Skills context was limited [SESSION_WRITE_BUSY]: another Skills process was updating this session's record, so newly selected skills are listed as load commands instead of being delivered. Load them with those commands when the task needs them.";
+/**
+ * Select and read context for one prompt, recording newly delivered skills in
+ * the session receipt.
+ *
+ * A new child's first receipt write fences its parent's exact receipt. When
+ * the parent recorded a load or committed a renewal while the child resolved
+ * (its pin itself unchanged), that write refuses with SESSION_PARENT_CHANGED;
+ * as the refusal prescribes, the child is resolved once more from the current
+ * parent pin. A parent whose pin changed (a migration or reconciliation), a
+ * second change, or no time left before options.resolveAgainBefore keeps the
+ * refusal.
+ *
+ * Receipt writes run synchronously and, under contention, block the calling
+ * thread for at most SESSION_WRITE_LOCK_WAIT_MS while they wait for another
+ * live writer's lock.
+ */
 export declare function buildSkillContext(input: SkillContextInput, options?: SkillContextOptions): Promise<SkillContextResult>;

package/dist/lib/skill-relevance.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Deterministic prompt relevance for selected skills. Pure metadata: it reads
+ * slugs, aliases and trigger keywords, never payloads, and builds no regular
+ * expression from profile data.
+ *
+ * - A keyword is a phrase: all of its words, in order and adjacent, in the
+ *   prompt. Duplicated keywords count once.
+ * - A selection without keywords is matched by its slug's words as a phrase:
+ *   the whole slug, or a shorter run of adjacent slug words that carries the
+ *   slug's own distinguishing word ("seating plan" for event-seating-plan, not
+ *   "compliance check" for grant-compliance-check or "run of" for
+ *   live-event-run-of-show), scored by the longest run that matched. A shorter
+ *   run needs two words of at least SLUG_CONTENT_WORD_MIN_LENGTH letters and
+ *   one of the slug's least-used words in this profile's triggers. Single slug
+ *   words never match on their own, except a one-word slug.
+ * - A one-word phrase counts only when it discriminates in this profile: a
+ *   word used by the triggers of more than DISCRIMINATING_WORD_MAX_SELECTIONS
+ *   selections (review, plan, check) says nothing on its own about which skill
+ *   a prompt needs.
+ * - A selection is named when the prompt contains its kebab-case slug or alias
+ *   with at least one hyphen, or a one-word name separated only by whitespace
+ *   from the word "skill" or "skills". A name raises priority and lets the
+ *   selection's own one-word triggers count, but never selects on its own.
+ * - A match much weaker than the prompt's best match (less than
+ *   WEAK_MATCH_FRACTION of its score) is marked weak: the prompt is about
+ *   something else, so it is offered as a load command, not injected. Named
+ *   selections are never weak.
+ * - An empty keyword list still disables prompt matching.
+ */
+import type { ResolvedSkillSelection } from "../types/skill-selection.js";
+/** A one-word trigger shared by more selections than this selects nothing alone. */
+export declare const DISCRIMINATING_WORD_MAX_SELECTIONS = 3;
+/** One matched phrase word is worth this much; a candidate needs at least one. */
+export declare const PHRASE_WORD_SCORE = 100;
+/** A match scoring below this fraction of the prompt's best match is weak. */
+export declare const WEAK_MATCH_FRACTION = 0.5;
+/** Shorter slug words (of, to, a) neither distinguish a slug nor fill a partial slug run. */
+export declare const SLUG_CONTENT_WORD_MIN_LENGTH = 3;
+export interface PromptRelevance {
+    selection: ResolvedSkillSelection;
+    /** 2 when the prompt names the selection, otherwise 1. */
+    priority: 1 | 2;
+    score: number;
+    /** The distinct phrases that counted, as normalized words. */
+    phrases: string[];
+    /** Much weaker than the prompt's best match; offered, not injected. */
+    weak: boolean;
+}
+export declare function promptWords(value: string): string[];
+interface SelectionPhrases {
+    phrases: string[][];
+    fromSlug: boolean;
+}
+/** The selection's distinct trigger phrases, or its slug's word runs when it has no keywords. */
+export declare function selectionPhrases(selection: Pick<ResolvedSkillSelection, "slug" | "triggers">): SelectionPhrases;
+/** How many selections use each word in any trigger phrase (each selection counted once). */
+export declare function triggerWordFrequency(selections: readonly Pick<ResolvedSkillSelection, "slug" | "triggers">[]): Map<string, number>;
+/**
+ * The slug's distinguishing words: among its words of at least
+ * SLUG_CONTENT_WORD_MIN_LENGTH letters, those used by the fewest selections'
+ * triggers in this profile (all of them when tied).
+ */
+export declare function slugAnchors(slugWords: readonly string[], frequency: ReadonlyMap<string, number>): Set<string>;
+/**
+ * Rank selections by prompt relevance. Only candidates with at least one
+ * counted phrase are returned, ordered by priority, then score, then slug.
+ */
+export declare function rankPromptRelevance(prompt: string, selections: readonly ResolvedSkillSelection[], frequency?: Map<string, number>): PromptRelevance[];
+/** At most this many weak prompt pointers are offered as load commands. */
+export declare const PROMPT_OFFER_LIMIT = 3;
+export type PromptOfferReason = "partial-match" | "common-word";
+export interface PromptOffer {
+    selection: ResolvedSkillSelection;
+    reason: PromptOfferReason;
+    evidence: number;
+}
+/**
+ * Selections the prompt points at too weakly to select, offered as `skills
+ * load` commands and never injected. Only trigger keywords count, never slug
+ * runs, and a selection the caller excludes (already selected, ranked or
+ * loaded) is skipped.
+ *
+ * - partial-match: all content words (at least SLUG_CONTENT_WORD_MIN_LENGTH
+ *   letters, two or more) of a multi-word keyword appear in the prompt, though
+ *   not as the phrase, and one of them discriminates in this profile
+ *   ("designs review" in "push the screens to the designs app for review").
+ * - common-word: a one-word keyword used by more than
+ *   DISCRIMINATING_WORD_MAX_SELECTIONS selections appears in the prompt.
+ *
+ * Partial matches rank before common words, then more matching keywords,
+ * then slug. A tie that does not fit the remaining offers is left out
+ * entirely: an alphabetical slug is no reason to prefer one.
+ */
+export declare function rankPromptOffers(prompt: string, selections: readonly ResolvedSkillSelection[], frequency?: Map<string, number>, exclude?: (selection: ResolvedSkillSelection) => boolean): PromptOffer[];
+export {};