hcifootprint 0.2.0

package/dist/serve/modes.js

@@ -0,0 +1,347 @@
+import { detectSchema } from 'footprintjs';
+import { normalizeSchema } from 'footprintjs/advanced';
+const SKILL_USAGE = ' Call with no arguments to open this skill and see its ready steps; call again with' +
+    " {step: '<name from readySteps>', input: {...}} to perform a step. High-effect steps additionally" +
+    ' need confirm: true. Steps arrive as DATA in results — they are never separate tools.';
+const WHATS_HERE_DESCRIPTION = 'Describe the current position: the page, the open skill (if any), what happened recently, ' +
+    'and the actions and skills available right now. Pass sinceVersion (the version from any ' +
+    'earlier result) to get only what changed since your last look — including what the user ' +
+    'did themselves in the meantime.';
+const DO_ACTION_DESCRIPTION = 'Perform one available action outside any skill flow. Call whats_here first to see action names. ' +
+    'High-effect actions additionally need confirm: true.';
+const WHY_DESCRIPTION = 'Explain why a state key currently holds its value: the causal chain of session actions — and ' +
+    'who fired each one — that produced it. Pass a state key name seen in results or guards.';
+const STEP_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        step: { type: 'string', description: 'A step name taken from readySteps in a previous result.' },
+        input: { type: 'object', description: 'The step input. Each result states what the next step expects.' },
+        confirm: { type: 'boolean', description: 'Required true for high-effect steps.' },
+        instance: {
+            type: 'string',
+            description: 'Which instance to act on, when the step lists instances (e.g. an order id).',
+        },
+    },
+    additionalProperties: false,
+};
+export function skillsAsTools(session, opts) {
+    const confirmHighEffect = opts?.confirmHighEffect ?? true;
+    const source = opts?.source ?? 'agent';
+    const graphId = session.graphId;
+    // Skills are declared-only data: the tool array derived from them is static
+    // BY CONSTRUCTION — freeze it once, serve identical bytes every turn.
+    const declaredSkills = session.availableSkills().skills;
+    const skillToolNames = new Map(); // tool name → skill id
+    for (const skill of declaredSkills) {
+        skillToolNames.set(sanitizeName(`${graphId}.skill.${skill.id}`), skill.id);
+    }
+    const skillSteps = new Map(declaredSkills.map((skill) => [skill.id, [...skill.steps]]));
+    const whatsHereName = sanitizeName(`${graphId}.whats_here`);
+    const doActionName = sanitizeName(`${graphId}.do_action`);
+    const whyName = sanitizeName(`${graphId}.why`);
+    const staticTools = [
+        ...declaredSkills.map((skill) => ({
+            name: sanitizeName(`${graphId}.skill.${skill.id}`),
+            description: skill.description + SKILL_USAGE,
+            inputSchema: structuredClone(STEP_INPUT_SCHEMA),
+        })),
+        {
+            name: whatsHereName,
+            description: WHATS_HERE_DESCRIPTION,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sinceVersion: {
+                        type: 'number',
+                        description: 'A version from a previous result: the reply narrates only the delta since it.',
+                    },
+                },
+                additionalProperties: false,
+            },
+        },
+        {
+            name: whyName,
+            description: WHY_DESCRIPTION,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    key: { type: 'string', description: 'A state key name, as seen in results, guards, or evidence.' },
+                },
+                required: ['key'],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: doActionName,
+            description: DO_ACTION_DESCRIPTION,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    action: { type: 'string', description: 'An action name from whats_here.' },
+                    input: structuredClone(STEP_INPUT_SCHEMA.properties.input),
+                    confirm: structuredClone(STEP_INPUT_SCHEMA.properties.confirm),
+                    instance: structuredClone(STEP_INPUT_SCHEMA.properties.instance),
+                },
+                required: ['action'],
+                additionalProperties: false,
+            },
+        },
+    ];
+    /** Currently-fireable edges by id — the serve layer's only view of tool detail. */
+    function edgeById() {
+        return new Map(session.available().edges.map((edge) => [edge.affordanceId, edge]));
+    }
+    function callSkill(skillId, args) {
+        // Cross-skill switch is implicit — but NEVER destructive-first: the open
+        // frame is left only after the target skill is known to be openable, so a
+        // blocked target cannot cost the model its current flow.
+        const openFrame = session.skillFrame();
+        if (openFrame && openFrame.skillId !== skillId) {
+            const target = session.availableSkills().skills.find((skill) => skill.id === skillId);
+            if (target && !target.preconditionPassed) {
+                return {
+                    ok: false,
+                    judgment: 'blocked',
+                    skill: skillId,
+                    why: 'This skill’s precondition does not hold right now. Your current skill is still open.',
+                    evidence: structuredClone(target.evidence),
+                    keptFrame: openFrame.skillId,
+                    ...positionData(),
+                };
+            }
+            session.leaveSkill();
+        }
+        if (!session.skillFrame()) {
+            const committed = session.commitSkill(skillId, { source });
+            if (!committed.ok) {
+                if (committed.reason === 'PRECONDITION_FAILED') {
+                    return {
+                        ok: false,
+                        judgment: 'blocked',
+                        skill: skillId,
+                        why: 'This skill’s precondition does not hold right now.',
+                        evidence: structuredClone(committed.evidence),
+                        ...positionData(),
+                    };
+                }
+                return { ok: false, judgment: 'error', skill: skillId, reason: committed.reason, ...positionData() };
+            }
+        }
+        if (args.step === undefined) {
+            return { ok: true, skill: skillId, ...frameData(skillId), ...positionData() };
+        }
+        const stepId = resolveStep(skillId, args.step);
+        if (!stepId) {
+            return {
+                ok: false,
+                judgment: 'error',
+                skill: skillId,
+                reason: 'UNKNOWN_STEP',
+                steps: [...(skillSteps.get(skillId) ?? [])],
+                ...positionData(),
+            };
+        }
+        const edge = edgeById().get(stepId);
+        if (confirmHighEffect && edge?.highEffect && args.confirm !== true) {
+            return {
+                ok: false,
+                judgment: 'needs-confirm',
+                skill: skillId,
+                step: stepId,
+                does: edge.description,
+                howToAct: 'Ask the human, then call again with confirm: true.',
+                ...positionData(),
+            };
+        }
+        const fired = session.fire(stepId, { source, payload: args.input, instance: args.instance });
+        // frameData FIRST: on a rejected fire, fireData's judgment ('rejected')
+        // must win over the frame's ('needs-choice'); on success fireData carries
+        // no judgment and the frame's stands.
+        return { skill: skillId, ...frameData(skillId), ...fireData(fired, stepId, edge), ...positionData() };
+    }
+    function resolveStep(skillId, step) {
+        const steps = skillSteps.get(skillId) ?? [];
+        if (steps.includes(step))
+            return step;
+        const matches = steps.filter((candidate) => candidate.endsWith(`.${step}`));
+        return matches.length === 1 ? matches[0] : null;
+    }
+    function callWhatsHere(sinceVersion) {
+        const brief = session.contextBrief(sinceVersion === undefined ? undefined : { sinceVersion });
+        return {
+            ok: true,
+            brief: brief.text,
+            actions: session.available().edges.map(edgeData),
+            skills: session.availableSkills().skills.map((skill) => ({
+                skill: skill.id,
+                does: skill.description,
+                feasible: skill.preconditionPassed,
+                ...(skill.preconditionUnevaluable ? { feasibilityUnknownFor: skill.preconditionUnevaluable } : {}),
+            })),
+            ...positionData(),
+        };
+    }
+    function callDoAction(args) {
+        const edges = session.available().edges;
+        const exact = edges.find((edge) => edge.affordanceId === args.action);
+        const matches = exact ? [exact] : edges.filter((edge) => edge.affordanceId.endsWith(`.${args.action}`));
+        if (matches.length !== 1) {
+            return {
+                ok: false,
+                judgment: 'error',
+                reason: matches.length === 0 ? 'UNKNOWN_ACTION' : 'AMBIGUOUS_ACTION',
+                actions: edges.map((edge) => edge.affordanceId),
+                ...positionData(),
+            };
+        }
+        const edge = matches[0];
+        if (confirmHighEffect && edge.highEffect && args.confirm !== true) {
+            return {
+                ok: false,
+                judgment: 'needs-confirm',
+                action: edge.affordanceId,
+                does: edge.description,
+                howToAct: 'Ask the human, then call again with confirm: true.',
+                ...positionData(),
+            };
+        }
+        const fired = session.fire(edge.affordanceId, { source, payload: args.input, instance: args.instance });
+        return { ...fireData(fired, edge.affordanceId, edge), ...positionData() };
+    }
+    // -- result builders (data channel; text = authored strings only) -----------
+    function positionData() {
+        return { youAreOn: session.node, version: session.version };
+    }
+    function frameData(skillId) {
+        const frame = session.skillFrame();
+        if (!frame || frame.skillId !== skillId) {
+            const closed = session
+                .frames()
+                .filter((candidate) => candidate.skillId === skillId)
+                .pop();
+            return closed ? { frame: closed.status } : {};
+        }
+        const plan = session.skillPlan(skillId);
+        if (plan.steps.every((step) => step.status === 'done' || step.status === 'inferred-done')) {
+            session.leaveSkill({ reason: 'completed' });
+            return { frame: 'completed', judgment: 'done' };
+        }
+        const edges = edgeById();
+        // A step whose fire is still awaiting the app's state report is NOT ready
+        // to fire again — advertising it would instruct the model to double-fire.
+        const awaiting = new Set(session.pending().map((pendingInfo) => pendingInfo.affordanceId));
+        const ready = plan.steps.filter((step) => step.status === 'ready' && !awaiting.has(step.affordanceId));
+        return {
+            frame: 'open',
+            judgment: ready.length === 0 ? 'navigate-or-wait' : ready.length === 1 ? 'one-ready-step' : 'needs-choice',
+            ...(awaiting.size > 0 ? { awaitingState: [...awaiting] } : {}),
+            readySteps: ready.map((step) => {
+                const edge = edges.get(step.affordanceId);
+                return {
+                    step: step.affordanceId,
+                    does: step.description,
+                    ...(edge?.highEffect ? { highEffect: true } : {}),
+                    ...(step.guardUnevaluated ? { guardUnevaluated: step.guardUnevaluated } : {}),
+                    ...expectsData(edge?.schema),
+                };
+            }),
+            laterSteps: plan.steps
+                .filter((step) => step.status !== 'ready')
+                .map((step) => ({ step: step.affordanceId, status: step.status })),
+            howToAct: 'Call this tool again with step set to one of readySteps.',
+        };
+    }
+    function fireData(fired, id, edge) {
+        if (fired.ok) {
+            return {
+                ok: true,
+                did: id,
+                settlement: fired.settlement,
+                // The transition id lets a caller fetch producedFor() AFTER awaiting the
+                // handler — the "act → data back" channel (the tool result is built
+                // synchronously here, before an async handler has produced anything).
+                transitionId: fired.transition.id,
+                // Copy: fired.transition is the LIVE record — a consumer mutating its
+                // result must never rewrite the trace.
+                ...(fired.transition.guardUnevaluated ? { guardUnevaluated: [...fired.transition.guardUnevaluated] } : {}),
+            };
+        }
+        return {
+            ok: false,
+            judgment: 'rejected',
+            did: id,
+            reason: fired.reason,
+            ...('evidence' in fired ? { evidence: structuredClone(fired.evidence) } : {}),
+            ...('issues' in fired ? { issues: fired.issues } : {}),
+            ...('instances' in fired ? { instances: [...fired.instances] } : {}),
+            ...('node' in fired ? { node: fired.node } : {}),
+            ...(fired.reason === 'PAYLOAD_INVALID' ? expectsData(edge?.schema) : {}),
+            ...(fired.reason === 'STILL_MOUNTING' ? { retriable: true } : {}),
+        };
+    }
+    function edgeData(edge) {
+        return {
+            action: edge.affordanceId,
+            does: edge.description,
+            ...(edge.highEffect ? { highEffect: true } : {}),
+            ...(edge.guardUnevaluated ? { guardUnevaluated: edge.guardUnevaluated } : {}),
+            ...(edge.instances ? { instances: edge.instances, enumeration: edge.enumeration } : {}),
+            ...(edge.activation && edge.activation !== 'registered' && edge.activation !== 'synced'
+                ? { activation: edge.activation }
+                : {}),
+        };
+    }
+    /** The step's expected input, rendered as DATA in the result (never as tool schema). */
+    function expectsData(schema) {
+        if (schema === undefined)
+            return {};
+        const kind = detectSchema(schema);
+        if (kind === 'zod')
+            return { expects: normalizeSchema(schema) };
+        if (kind === 'json-schema')
+            return { expects: structuredClone(schema) };
+        return { expects: 'validated at fire time (non-serializable validator)' };
+    }
+    return {
+        tools: () => structuredClone(staticTools),
+        call(name, args) {
+            const parsed = (args ?? {});
+            const skillId = skillToolNames.get(name);
+            if (skillId !== undefined) {
+                return callSkill(skillId, {
+                    step: typeof parsed['step'] === 'string' ? parsed['step'] : undefined,
+                    input: parsed['input'],
+                    confirm: parsed['confirm'] === true,
+                    instance: typeof parsed['instance'] === 'string' ? parsed['instance'] : undefined,
+                });
+            }
+            if (name === whatsHereName) {
+                return callWhatsHere(typeof parsed['sinceVersion'] === 'number' ? parsed['sinceVersion'] : undefined);
+            }
+            if (name === whyName) {
+                if (typeof parsed['key'] !== 'string' || !parsed['key']) {
+                    return { ok: false, judgment: 'error', reason: 'KEY_REQUIRED' };
+                }
+                // The slice text is DATA (it can carry committed state values) — it
+                // rides the result channel like producedFor(), never a description.
+                return { ok: true, key: parsed['key'], why: session.why(parsed['key']), ...positionData() };
+            }
+            if (name === doActionName) {
+                if (typeof parsed['action'] !== 'string' || !parsed['action']) {
+                    return { ok: false, judgment: 'error', reason: 'ACTION_REQUIRED' };
+                }
+                return callDoAction({
+                    action: parsed['action'],
+                    input: parsed['input'],
+                    confirm: parsed['confirm'] === true,
+                    instance: typeof parsed['instance'] === 'string' ? parsed['instance'] : undefined,
+                });
+            }
+            return { ok: false, judgment: 'error', reason: 'UNKNOWN_TOOL', tools: staticTools.map((tool) => tool.name) };
+        },
+    };
+}
+function sanitizeName(name) {
+    return name.replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+//# sourceMappingURL=modes.js.map

package/dist/serve/modes.js.map

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

package/dist/testing/harness.d.ts

@@ -0,0 +1,156 @@
+import type { DoActionArgs, ServeResult, SkillCallArgs } from '../serve/modes.js';
+import type { NavigationGraph } from '../tree/types.js';
+import type { InteractionSession, ToolGroupHandle } from '../traverse/nav-session.js';
+import type { FireResult, GapRecord, StimulusKind, TransitionRecord } from '../atom/types.js';
+import type { MCPToolDescription } from 'footprintjs';
+export interface ResolverContext<State> {
+    /** The current projected state, as the real handler would read it. */
+    state: State;
+}
+export interface ResolverOutcome<State> {
+    /**
+     * The state change this action makes — reported through the REAL updateState,
+     * so the session verifies it against the action's declared writes. Keep it
+     * EXPLICIT (do not mirror effect.writes) or the drift check rubber-stamps
+     * itself: the whole value is that the graph's claim and the mock's real delta
+     * are independent.
+     */
+    patch?: Partial<State> & Record<string, unknown>;
+    /** Navigate to this page after the delta (like the app's router confirming). */
+    goTo?: string;
+    /** The "act → data back" return value (search results, a looked-up record). */
+    produced?: unknown;
+}
+/** One mock handler for an action. Synchronous — runs inside the precise-attribution window. */
+export type Resolver<State> = (payload: unknown, ctx: ResolverContext<State>) => ResolverOutcome<State> | void;
+/** A controllable clock for deterministic time-dependent staleness tests. */
+export interface TestClock {
+    now(): number;
+    set(ms: number): void;
+    advance(ms: number): void;
+}
+export interface DriftReport {
+    /** True when no declared-effect drift was observed (the release-readiness signal). */
+    ok: boolean;
+    /** Actions whose settled delta did not cover their declared writes — the graph drifted from the handler. */
+    effectDrift: Array<{
+        transitionId: string;
+        affordanceId: string;
+        declaredWrites: string[];
+    }>;
+    /** Guard keys taken on faith because the state view never held them (honesty, not failure). */
+    unevaluatedGuards: Array<{
+        transitionId: string;
+        affordanceId: string;
+        keys: string[];
+    }>;
+    /** The unmet-demand ledger: refused fires + reported gaps. */
+    gaps: GapRecord[];
+}
+export interface TestAppOptions<State> {
+    /** The initial projected state (guards read it; enables the state tap). */
+    initialState?: State;
+    /** One mock handler per action, keyed by affordance id (qualified or bare/leaf). */
+    resolvers?: Record<string, Resolver<State>>;
+    /** Starting page (default: the graph's first page). */
+    node?: string;
+    /** Fail the test the instant declared-effect drift appears. Default false (report-by-default). */
+    strict?: boolean;
+    /** Keys stored redacted in the commit log. */
+    redactedKeys?: string[];
+    /** Dormancy grace window for the drift/overlay timers (default 3000ms). */
+    dormantGraceMs?: number;
+    /** Sink for the session's dev warnings (default: collected, readable via warnings()). */
+    onWarn?: (message: string) => void;
+    /**
+     * Bring your own already-wired session (real registerToolGroup / taps) for
+     * full integration fidelity. In this mode the harness does NOT auto-mount or
+     * inject a clock — it wraps what you built. `graph`/`resolvers` are ignored.
+     */
+    session?: InteractionSession;
+}
+export interface TestApp<State> {
+    /** The real session under the hood — drop to it for anything the facade omits. */
+    readonly session: InteractionSession;
+    /** The current page id. */
+    readonly node: string;
+    /** The session cursor version. */
+    readonly version: number;
+    /** A detached snapshot of the projected state. */
+    state(): State;
+    /** Dev warnings the session emitted (StrictMode notes, handler errors, drift warnings). */
+    warnings(): string[];
+    /** The controllable clock (deterministic dormancy/mount-grace tests). */
+    readonly clock: TestClock;
+    /** Advance the injected clock (sugar for clock.advance). */
+    advanceTime(ms: number): void;
+    /** Drive like a human click. Throws on rejection (fail-fast). */
+    readonly user: {
+        /** Fire, auto-settle, return the settled record. Throws if the fire is refused. */
+        fire(affordanceId: string, opts?: {
+            payload?: unknown;
+            instance?: string;
+        }): Promise<TransitionRecord>;
+        /** Fire + auto-settle but NEVER throw — return the raw FireResult (inspect a rejection). */
+        tryFire(affordanceId: string, opts?: {
+            payload?: unknown;
+            instance?: string;
+        }): Promise<FireResult>;
+        /** Fire WITHOUT auto-settling — observe the pending/optimistic-UI window yourself. */
+        fireRaw(affordanceId: string, opts?: {
+            payload?: unknown;
+            instance?: string;
+        }): FireResult;
+    };
+    /** Drive like the planning LLM, through the real Mode B port. Returns ServeResult (needs-confirm is data, never a throw). */
+    readonly agent: {
+        /** The FIXED tool array the model sees (one per skill + whats_here/do_action). */
+        tools(): MCPToolDescription[];
+        /** Call whats_here. */
+        whatsHere(): Promise<ServeResult>;
+        /** Open/step a skill by its id (maps to the skill's fixed tool). */
+        skill(skillId: string, args?: SkillCallArgs): Promise<ServeResult>;
+        /** Perform one action outside a skill flow (do_action). */
+        do(action: string, args?: Omit<DoActionArgs, 'action'>): Promise<ServeResult>;
+    };
+    /** A world-initiated state change (server push, background update) — never blamed on a pending fire. */
+    stimulus(patch: Partial<State> & Record<string, unknown>, opts?: {
+        stimulus?: StimulusKind;
+    }): void;
+    /** The browser back button (or any external navigation) — recorded as a stimulus sync. */
+    back(page: string): void;
+    /** Mount + show a modal/tab node's tools (not auto-mounted). Returns its handle. */
+    open(path: string, opts?: {
+        instance?: string;
+    }): ToolGroupHandle;
+    /** Unmount a node opened with open(). */
+    close(path: string): void;
+    /** Drain to quiescence (auto-called by user.fire/agent.*; call it after fireRaw/stimulus). */
+    settled(): Promise<void>;
+    /** The honesty-marker drift report — the release-readiness signal. */
+    report(): DriftReport;
+    /** Assert the cursor is on `page`. */
+    expectOn(page: string): void;
+    /** Assert the projected state contains these key/value pairs (deep). */
+    expectState(partial: Partial<State> & Record<string, unknown>): void;
+    /** Assert an action (by id or bare/leaf suffix) is available right now. */
+    expectAvailable(affordanceId: string): void;
+    /** Assert a FireResult was refused (optionally with a specific reason, e.g. 'GUARD_FAILED'). */
+    expectRejected(result: FireResult, reason?: string): void;
+    /** Assert a skill has a completed frame in the history. */
+    expectSkillCompleted(skillId: string): void;
+    /** Assert no declared-effect drift (optionally also fail on any gaps). The opt-in release gate. */
+    expectClean(opts?: {
+        includeGaps?: boolean;
+    }): void;
+}
+/**
+ * Build a headless test harness over a navigation graph. Wires each resolver as
+ * a real handler, auto-mounts the current page's tools, and drives the real
+ * session — so tests exercise production code, not a copy.
+ */
+export declare function testApp<State extends Record<string, unknown> = Record<string, unknown>>(graph: NavigationGraph, options?: TestAppOptions<State>): TestApp<State>;
+export declare function testApp<State extends Record<string, unknown> = Record<string, unknown>>(options: TestAppOptions<State> & {
+    session: InteractionSession;
+}): TestApp<State>;
+//# sourceMappingURL=harness.d.ts.map

package/dist/testing/harness.d.ts.map

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