@aotui/mobile-ai-native 0.1.0-alpha.2 → 0.1.0-alpha.3

package/GUIDE.md

@@ -1,6 +1,6 @@
-# GUIDE: Building an Agent Native iOS Calendar App
+# GUIDE: Building an Agent Native Mobile App
 
-This guide is for a developer who wants to build a high-quality agent-native calendar app on iOS using `@aotui/mobile-ai-native`.
+This guide is for a developer who wants to build a high-quality agent-native mobile app using `@aotui/mobile-ai-native`.
 
 Important boundary:
 
@@ -10,7 +10,7 @@ Important boundary:
 The goal is simple:
 
 - humans use a normal GUI calendar
-- the LLM uses tools through a snapshot
+- the LLM uses a stable tool manifest through a snapshot
 - both operate on the same app state
 - the human can see the result of the LLM's actions
 
@@ -48,7 +48,15 @@ In the current runtime, the snapshot is assembled from ordered `<View>` fragment
 - `markup` is the composed xml+markdown snapshot
 - `views` preserves the fragment order
 - `refIndex` resolves semantic refs by exact key lookup
-- `visibleTools` is the tool list for that same render tick
+- `tools` is the stable tool manifest for that same render tick
+- `toolAvailability` tells the model which tools are currently executable
+- `preconditions` describe why a tool exists and what state it assumes
+
+The important split is:
+
+- `tools` stay stable across ticks unless the app protocol itself changes
+- `toolAvailability` can change as state changes
+- `PRECONDITION_NOT_MET` is the structured failure when a tool exists but cannot run yet
 
 `snapshotId` is non-negotiable.
 If the app changes after the LLM reads a snapshot, the tool call must still be tied to the exact snapshot the model saw.
@@ -129,13 +137,14 @@ Model the app as a static root plus mounted runtime views:
 - `EventDetailView` can mount only when an event is selected
 - `SearchResultView` can mount only while search results are present
 
-The tool surface should follow the same semantic grouping.
+The tool surface should be stable by default.
 
-- register tools against a `viewType`
-- filter them with `visibility(state)`
-- only expose tools for currently relevant view types
+- register protocol tools with `exposure: "static"`
+- use `getAvailability(state)` to report whether the tool can run now
+- use `preconditions` to explain the contract in human-readable form
+- reserve `exposure: "dynamic"` for the few tools that are truly view-scoped
 
-That keeps the calendar agent surface aligned with the current screen reality without pretending the runtime is a desktop tree inspector.
+That keeps the calendar agent surface aligned with the current screen reality without forcing every temporary GUI state into the visible tool list.
 
 ## 7. Why Refs Matter In Calendar Apps
 
@@ -215,6 +224,7 @@ The React Native app should do only host work:
 - host the agent session
 - ask the framework for `SnapshotBundle`
 - pass tool calls into `executeTool`
+- read `toolAvailability` when it wants to surface current precondition state in the UI
 - subscribe to state and trace through the runtime hooks instead of copying framework state into local component state
 
 In practice, that means mounting the core through `createReactNativeAppRuntime()` and `AppRuntimeProvider` from `@aotui/mobile-ai-native-react-native`.

package/README.md

@@ -16,7 +16,7 @@ The current snapshot model is view-based:
 - one shared state system drives both GUI and TUI
 - the root view is static navigation knowledge, not runtime state
 - business views are mounted from current state and represent runtime reality
-- tools are scoped by `viewType` and then filtered by `visibility(state)`
+- tools are exposed as a stable manifest, with runtime availability tracked separately
 - the framework builds one atomic `SnapshotBundle`
 - snapshot markup is composed from ordered `<View>` fragments
 - tools execute against the exact `snapshotId` the LLM saw
@@ -36,7 +36,8 @@ type SnapshotBundle = {
   views: readonly ViewFragment[];
   tui: string;
   refIndex: Record<string, RefIndexEntry>;
-  visibleTools: readonly ToolDefinition[];
+  tools: readonly ToolDefinition[];
+  toolAvailability: Record<string, ToolAvailability>;
 };
 ```
 
@@ -45,7 +46,7 @@ Current behavior to keep in mind:
 - `markup` is the composed xml+markdown snapshot built from ordered `<View>` fragments
 - `views` preserves the ordered fragment list, with the `Root` fragment first
 - `tui` is retained as a compatibility readout and may differ from `markup`, but it should be produced from the same snapshot generation pass
-- `refIndex` and `visibleTools` are produced and frozen alongside snapshot creation
+- `refIndex`, `tools`, and `toolAvailability` are produced and frozen alongside snapshot creation
 
 The bundle is intended to be atomic:
 
@@ -53,9 +54,10 @@ The bundle is intended to be atomic:
 - `views`
 - `tui`
 - `refIndex`
-- `visibleTools`
+- `tools`
+- `toolAvailability`
 
-Today the runtime hard-validates `markup` against `views`, then freezes the associated `tui`, `refIndex`, and `visibleTools` outputs generated on that same snapshot path.
+Today the runtime hard-validates `markup` against `views`, then freezes the associated `tui`, `refIndex`, `tools`, and `toolAvailability` outputs generated on that same snapshot path.
 
 ## RootView And Mounted Views
 
@@ -81,13 +83,13 @@ That means the LLM should read the static root first, then read the mounted busi
 
 ## Tool Model
 
-Tools are defined against a semantic `viewType`, then filtered by current state.
+Tools are defined against a semantic `viewType`, exposure mode, and runtime availability.
 
 That gives the runtime this rule:
 
-`visibleTools = tools for currently relevant viewTypes + visibility(state)`
+`tools = stable tools + currently exposed dynamic tools`
 
-So a tool can exist in the app, be mounted to a view type, and still be hidden when the current state does not allow it.
+Then `toolAvailability[name]` tells the model whether a listed tool can execute right now. A tool can remain in the manifest and still fail with `PRECONDITION_NOT_MET` when current state does not satisfy its runtime guard.
 
 ## Core Contract
 
@@ -177,4 +179,4 @@ Keep the framework and app responsibilities separated:
 - business apps own state shape, domain actions, handwritten TUI, and app-specific effect behavior
 - actions can read state, emit events, run effects, and update trace summaries
 - effects can read state, emit events, and report structured success or failure, but they do not write state directly
-- snapshot coherence is enforced for the textual view representation, so `markup`, `views`, and `tui` must agree for the same render tick; `refIndex` and `visibleTools` are built and frozen alongside that snapshot path but are not yet cross-validated field-by-field
+- snapshot coherence is enforced for the textual view representation, so `markup`, `views`, and `tui` must agree for the same render tick; `refIndex`, `tools`, and `toolAvailability` are built and frozen alongside that snapshot path but are not yet cross-validated field-by-field

package/dist/core/action/createActionRuntime.d.ts

@@ -1,6 +1,6 @@
 import type { ActionDefinition } from "./defineAction.js";
 import type { EffectMap } from "../effect/types.js";
-import type { ActionResult, Store, ToolDefinition, TraceStore } from "../types.js";
+import type { ActionResult, Store, ToolAvailability, TraceStore } from "../types.js";
 export declare function createActionRuntime<State, Event>(config: {
     store: Store<State, Event>;
     actions: Array<ActionDefinition<State, Event, any>>;
@@ -9,5 +9,10 @@ export declare function createActionRuntime<State, Event>(config: {
     getRelevantViewTypes?: () => readonly string[];
 }): {
     executeAction: (name: string, input: Record<string, unknown>) => Promise<ActionResult>;
-    listVisibleTools: (relevantViewTypes?: readonly string[]) => ToolDefinition[];
+    listTools: () => readonly import("../types").ToolDefinition[];
+    getToolAvailability: () => Readonly<Record<string, ToolAvailability>>;
+    getToolSurface: () => {
+        tools: readonly import("../types").ToolDefinition[];
+        toolAvailability: Readonly<Record<string, ToolAvailability>>;
+    };
 };

package/dist/core/action/createActionRuntime.js

@@ -1,8 +1,10 @@
+import { materializeToolSurface } from "./materializeToolSurface.js";
 import { createTraceStore } from "../trace/createTraceStore.js";
 export function createActionRuntime(config) {
     const actionsByName = new Map(config.actions.map((action) => [action.name, action]));
     const traceStore = config.traceStore ?? createTraceStore();
-    function isActionRelevant(action) {
+    const AVAILABLE = Object.freeze({ ok: true });
+    function isActionViewTypeRelevant(action) {
         const scopedAction = action;
         const relevantViewTypes = config.getRelevantViewTypes?.() ?? [];
         if (!scopedAction.viewType) {
@@ -10,6 +12,18 @@ export function createActionRuntime(config) {
         }
         return relevantViewTypes.includes(scopedAction.viewType);
     }
+    function isActionExposed(action) {
+        if (action.exposure !== "dynamic") {
+            return true;
+        }
+        if (!isActionViewTypeRelevant(action)) {
+            return false;
+        }
+        return action.isExposed?.(config.store.getState()) ?? true;
+    }
+    function getActionAvailability(action) {
+        return action.getAvailability?.(config.store.getState()) ?? AVAILABLE;
+    }
     function recordTrace(actionName, status, summary) {
         traceStore.record({
             actionName,
@@ -28,13 +42,12 @@ export function createActionRuntime(config) {
                 },
             };
         }
-        if (!isActionRelevant(action) ||
-            !action.visibility(config.store.getState())) {
+        if (!isActionExposed(action)) {
             return {
                 success: false,
                 error: {
-                    code: "ACTION_NOT_VISIBLE",
-                    message: `Action ${name} is not currently visible`,
+                    code: "ACTION_NOT_EXPOSED",
+                    message: `Action ${name} is not currently exposed`,
                 },
             };
         }
@@ -48,6 +61,20 @@ export function createActionRuntime(config) {
                 },
             };
         }
+        const availability = getActionAvailability(action);
+        if (!availability.ok) {
+            return {
+                success: false,
+                error: {
+                    code: availability.code,
+                    message: availability.message,
+                    ...(availability.reason ? { reason: availability.reason } : {}),
+                    ...(availability.requiredState
+                        ? { requiredState: availability.requiredState }
+                        : {}),
+                },
+            };
+        }
         let latestSummary = `Started action ${name}`;
         recordTrace(name, "started", latestSummary);
         const trace = {
@@ -92,31 +119,23 @@ export function createActionRuntime(config) {
             throw error;
         }
     }
-    function listVisibleTools(relevantViewTypes = config.getRelevantViewTypes?.() ?? []) {
-        const state = config.store.getState();
-        const relevantViewTypeSet = new Set(relevantViewTypes);
-        return config.actions
-            .filter((action) => {
-            const scopedAction = action;
-            const isViewTypeRelevant = !scopedAction.viewType ||
-                relevantViewTypeSet.has(scopedAction.viewType);
-            return isViewTypeRelevant && action.visibility(state);
-        })
-            .map((action) => {
-            const scopedAction = action;
-            return {
-                name: action.name,
-                description: action.description,
-                inputSchema: action.schema,
-                meta: action.meta ?? {},
-                ...(scopedAction.viewType
-                    ? { viewType: scopedAction.viewType }
-                    : {}),
-            };
+    function getToolSurface() {
+        return materializeToolSurface({
+            actions: config.actions,
+            isActionExposed,
+            getActionAvailability,
         });
     }
+    function listTools() {
+        return getToolSurface().tools;
+    }
+    function getToolAvailability() {
+        return getToolSurface().toolAvailability;
+    }
     return {
         executeAction,
-        listVisibleTools,
+        listTools,
+        getToolAvailability,
+        getToolSurface,
     };
 }

package/dist/core/action/defineAction.d.ts

@@ -1,6 +1,6 @@
 import type { ZodType } from "zod";
 import type { EffectResult } from "../effect/types.js";
-import type { ActionResult, ToolMetadata } from "../types.js";
+import type { ActionResult, ToolAvailability, ToolExposure, ToolMetadata } from "../types.js";
 export type ActionContext<State, Event> = {
     getState(): State;
     emit(event: Event): void;
@@ -14,7 +14,10 @@ export type ActionDefinition<State, Event, Input> = {
     description: string;
     schema: ZodType<Input>;
     meta?: ToolMetadata;
-    visibility(state: State): boolean;
+    exposure?: ToolExposure;
+    preconditions?: readonly string[];
+    isExposed?(state: State): boolean;
+    getAvailability?(state: State): ToolAvailability;
     handler(ctx: ActionContext<State, Event>, input: Input): Promise<ActionResult> | ActionResult;
 };
 export declare function defineAction<State, Event, Input>(config: ActionDefinition<State, Event, Input>): ActionDefinition<State, Event, Input>;

package/dist/core/action/defineViewTypeTool.d.ts

@@ -2,4 +2,15 @@ import type { ActionDefinition } from "./defineAction.js";
 export type ViewTypeToolActionDefinition<State, Event, Input> = ActionDefinition<State, Event, Input> & {
     readonly viewType: string;
 };
-export declare function defineViewTypeTool<State, Event, Input>(tool: ViewTypeToolActionDefinition<State, Event, Input>): ViewTypeToolActionDefinition<State, Event, Input>;
+export declare function defineViewTypeTool<State, Event, Input>(tool: ViewTypeToolActionDefinition<State, Event, Input>): {
+    name: string;
+    description: string;
+    schema: import("zod").ZodType<Input, unknown, import("zod/v4/core").$ZodTypeInternals<Input, unknown>>;
+    meta?: import("../types").ToolMetadata;
+    exposure: string;
+    preconditions?: readonly string[];
+    isExposed?(state: State): boolean;
+    getAvailability?(state: State): import("../types").ToolAvailability;
+    handler(ctx: import("./defineAction").ActionContext<State, Event>, input: Input): Promise<import("../types").ActionResult> | import("../types").ActionResult;
+    viewType: string;
+};

package/dist/core/action/defineViewTypeTool.js

@@ -1,3 +1,6 @@
 export function defineViewTypeTool(tool) {
-    return tool;
+    return {
+        exposure: "dynamic",
+        ...tool,
+    };
 }

package/dist/core/action/materializeToolSurface.d.ts

@@ -0,0 +1,10 @@
+import type { ActionDefinition } from "./defineAction.js";
+import type { ToolAvailability, ToolDefinition } from "../types.js";
+export declare function materializeToolSurface<State, Event>(config: {
+    actions: Array<ActionDefinition<State, Event, any>>;
+    isActionExposed: (action: ActionDefinition<State, Event, any>) => boolean;
+    getActionAvailability: (action: ActionDefinition<State, Event, any>) => ToolAvailability;
+}): {
+    tools: readonly ToolDefinition[];
+    toolAvailability: Readonly<Record<string, ToolAvailability>>;
+};

package/dist/core/action/materializeToolSurface.js

@@ -0,0 +1,25 @@
+import { hardenToolAvailability, hardenTools, } from "../tool/hardenToolSurface.js";
+export function materializeToolSurface(config) {
+    const tools = [];
+    const toolAvailability = Object.create(null);
+    for (const action of config.actions) {
+        if (!config.isActionExposed(action)) {
+            continue;
+        }
+        const scopedAction = action;
+        tools.push({
+            name: action.name,
+            description: action.description,
+            inputSchema: action.schema,
+            meta: action.meta ?? {},
+            exposure: action.exposure ?? "static",
+            preconditions: action.preconditions ?? [],
+            ...(scopedAction.viewType ? { viewType: scopedAction.viewType } : {}),
+        });
+        toolAvailability[action.name] = config.getActionAvailability(action);
+    }
+    return {
+        tools: hardenTools(tools),
+        toolAvailability: hardenToolAvailability(toolAvailability),
+    };
+}

package/dist/core/snapshot/createSnapshotBundle.d.ts

@@ -1,9 +1,10 @@
-import type { SnapshotBundle, ToolDefinition, RefIndexEntry, ViewFragment } from "../types.js";
+import type { SnapshotBundle, RefIndexEntry, ToolAvailability, ToolDefinition, ViewFragment } from "../types.js";
 export declare function hardenSnapshotBundle(snapshot: SnapshotBundle): SnapshotBundle;
 export declare function createSnapshotBundle(input: {
     markup?: string;
     views?: readonly ViewFragment[];
     tui?: string;
     refIndex: Readonly<Record<string, RefIndexEntry>>;
-    visibleTools: readonly ToolDefinition[];
+    tools: readonly ToolDefinition[];
+    toolAvailability: Readonly<Record<string, ToolAvailability>>;
 }): SnapshotBundle;

package/dist/core/snapshot/createSnapshotBundle.js

@@ -1,59 +1,5 @@
+import { cloneReadonlyValue, hardenToolAvailability, hardenTools, } from "../tool/hardenToolSurface.js";
 let snapshotCounter = 0;
-function isPlainObject(value) {
-    if (typeof value !== "object" || value === null) {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
-function cloneReadonlyValue(value, seen = new WeakMap()) {
-    if (value === null) {
-        return null;
-    }
-    const valueType = typeof value;
-    if (valueType === "string" ||
-        valueType === "boolean") {
-        return value;
-    }
-    if (valueType === "number") {
-        if (!Number.isFinite(value)) {
-            throw new Error("Snapshot values must be plain JSON-like data; received a non-finite number.");
-        }
-        return value;
-    }
-    if (valueType === "undefined" ||
-        valueType === "function" ||
-        valueType === "symbol" ||
-        valueType === "bigint") {
-        throw new Error("Snapshot values must be plain JSON-like data; received an unsupported primitive value.");
-    }
-    if (Array.isArray(value)) {
-        if (seen.has(value)) {
-            return seen.get(value);
-        }
-        const clone = [];
-        seen.set(value, clone);
-        for (const item of value) {
-            clone.push(cloneReadonlyValue(item, seen));
-        }
-        return Object.freeze(clone);
-    }
-    if (isPlainObject(value)) {
-        if (seen.has(value)) {
-            return seen.get(value);
-        }
-        const clone = Object.create(null);
-        seen.set(value, clone);
-        for (const [key, nestedValue] of Object.entries(value)) {
-            clone[key] = cloneReadonlyValue(nestedValue, seen);
-        }
-        return Object.freeze(clone);
-    }
-    if (typeof value === "object" && value !== null) {
-        throw new Error("Snapshot values must be plain JSON-like data; received a non-plain object.");
-    }
-    return value;
-}
 function hardenRefIndex(refIndex) {
     const clonedEntries = Object.create(null);
     for (const [refId, entry] of Object.entries(refIndex)) {
@@ -64,16 +10,6 @@ function hardenRefIndex(refIndex) {
     }
     return Object.freeze(clonedEntries);
 }
-function hardenVisibleTools(visibleTools) {
-    const clonedTools = visibleTools.map((tool) => Object.freeze({
-        name: tool.name,
-        description: tool.description,
-        inputSchema: tool.inputSchema,
-        meta: cloneReadonlyValue(tool.meta),
-        ...(tool.viewType ? { viewType: tool.viewType } : {}),
-    }));
-    return Object.freeze(clonedTools);
-}
 function validateSnapshotCoherence(snapshot) {
     if (snapshot.views.length === 0) {
         return;
@@ -97,7 +33,8 @@ export function hardenSnapshotBundle(snapshot) {
         }))),
         tui: snapshot.tui,
         refIndex: hardenRefIndex(snapshot.refIndex),
-        visibleTools: hardenVisibleTools(snapshot.visibleTools),
+        tools: hardenTools(snapshot.tools),
+        toolAvailability: hardenToolAvailability(snapshot.toolAvailability),
     });
 }
 export function createSnapshotBundle(input) {
@@ -114,6 +51,7 @@ export function createSnapshotBundle(input) {
         views,
         tui,
         refIndex: input.refIndex,
-        visibleTools: input.visibleTools,
+        tools: input.tools,
+        toolAvailability: input.toolAvailability,
     });
 }

package/dist/core/tool/hardenToolSurface.d.ts

@@ -0,0 +1,4 @@
+import type { ToolAvailability, ToolDefinition } from "../types.js";
+export declare function cloneReadonlyValue(value: unknown, seen?: WeakMap<object, unknown>): unknown;
+export declare function hardenTools(tools: readonly ToolDefinition[]): readonly ToolDefinition[];
+export declare function hardenToolAvailability(toolAvailability: Readonly<Record<string, ToolAvailability>>): Readonly<Record<string, ToolAvailability>>;

package/dist/core/tool/hardenToolSurface.js

@@ -0,0 +1,85 @@
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+export function cloneReadonlyValue(value, seen = new WeakMap()) {
+    if (value === null) {
+        return null;
+    }
+    const valueType = typeof value;
+    if (valueType === "string" || valueType === "boolean") {
+        return value;
+    }
+    if (valueType === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("Tool protocol values must be plain JSON-like data; received a non-finite number.");
+        }
+        return value;
+    }
+    if (valueType === "undefined" ||
+        valueType === "function" ||
+        valueType === "symbol" ||
+        valueType === "bigint") {
+        throw new Error("Tool protocol values must be plain JSON-like data; received an unsupported primitive value.");
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            return seen.get(value);
+        }
+        const clone = [];
+        seen.set(value, clone);
+        for (const item of value) {
+            clone.push(cloneReadonlyValue(item, seen));
+        }
+        return Object.freeze(clone);
+    }
+    if (isPlainObject(value)) {
+        if (seen.has(value)) {
+            return seen.get(value);
+        }
+        const clone = Object.create(null);
+        seen.set(value, clone);
+        for (const [key, nestedValue] of Object.entries(value)) {
+            clone[key] = cloneReadonlyValue(nestedValue, seen);
+        }
+        return Object.freeze(clone);
+    }
+    if (typeof value === "object" && value !== null) {
+        throw new Error("Tool protocol values must be plain JSON-like data; received a non-plain object.");
+    }
+    return value;
+}
+export function hardenTools(tools) {
+    const clonedTools = tools.map((tool) => Object.freeze({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        meta: cloneReadonlyValue(tool.meta),
+        exposure: tool.exposure,
+        preconditions: Object.freeze([...tool.preconditions]),
+        ...(tool.viewType ? { viewType: tool.viewType } : {}),
+    }));
+    return Object.freeze(clonedTools);
+}
+export function hardenToolAvailability(toolAvailability) {
+    const clonedAvailability = Object.create(null);
+    for (const [toolName, availability] of Object.entries(toolAvailability)) {
+        clonedAvailability[toolName] = availability.ok
+            ? Object.freeze({ ok: true })
+            : Object.freeze({
+                ok: false,
+                code: availability.code,
+                message: availability.message,
+                ...(availability.reason ? { reason: availability.reason } : {}),
+                ...(availability.requiredState
+                    ? {
+                        requiredState: cloneReadonlyValue(availability.requiredState),
+                    }
+                    : {}),
+            });
+    }
+    return Object.freeze(clonedAvailability);
+}

package/dist/core/types.d.ts

@@ -14,11 +14,23 @@ export type RefIndexEntry = {
     readonly value: unknown;
 };
 export type ToolMetadata = Readonly<Record<string, unknown>>;
+export type ToolExposure = "static" | "dynamic";
+export type ToolAvailability = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: "PRECONDITION_NOT_MET";
+    readonly message: string;
+    readonly reason?: string;
+    readonly requiredState?: Readonly<Record<string, unknown>>;
+};
 export type ToolDefinition = {
     readonly name: string;
     readonly description: string;
     readonly inputSchema: ZodTypeAny;
     readonly meta: ToolMetadata;
+    readonly exposure: ToolExposure;
+    readonly preconditions: readonly string[];
     readonly viewType?: string;
 };
 export type ViewTypeToolDefinition = ToolDefinition & {
@@ -46,7 +58,8 @@ export type SnapshotAssemblerInput<State = unknown> = {
     readonly rootView: ViewFragment;
     readonly mountedViews: readonly ViewFragment[];
     readonly refIndex: Readonly<Record<string, RefIndexEntry>>;
-    readonly visibleTools: readonly ToolDefinition[];
+    readonly tools: readonly ToolDefinition[];
+    readonly toolAvailability: Readonly<Record<string, ToolAvailability>>;
     readonly tui?: string;
 };
 export type SnapshotBundle = {
@@ -56,7 +69,8 @@ export type SnapshotBundle = {
     readonly views: readonly ViewFragment[];
     readonly tui: string;
     readonly refIndex: Readonly<Record<string, RefIndexEntry>>;
-    readonly visibleTools: readonly ToolDefinition[];
+    readonly tools: readonly ToolDefinition[];
+    readonly toolAvailability: Readonly<Record<string, ToolAvailability>>;
 };
 export type SnapshotStatus = "active" | "stale";
 export type SnapshotRegistryEntry = {
@@ -77,5 +91,7 @@ export type ActionResult<T = unknown> = {
     error?: {
         code: string;
         message: string;
+        reason?: string;
+        requiredState?: Readonly<Record<string, unknown>>;
     };
 };

package/dist/demo/inbox/InboxTUI.d.ts

@@ -1,3 +1,3 @@
-import type { ToolDefinition } from "../../core/types.js";
+import type { ToolAvailability, ToolDefinition } from "../../core/types.js";
 import type { InboxState } from "./state.js";
-export declare function createInboxSnapshotBundle(state: InboxState, visibleTools: readonly ToolDefinition[]): import("../..").SnapshotBundle;
+export declare function createInboxSnapshotBundle(state: InboxState, tools: readonly ToolDefinition[], toolAvailability: Readonly<Record<string, ToolAvailability>>): import("../..").SnapshotBundle;

package/dist/demo/inbox/InboxTUI.js

@@ -8,6 +8,25 @@ import { RefProvider } from "../../ref/RefContext.js";
 import { useDataRef } from "../../ref/useDataRef.js";
 import { useArrayRef } from "../../ref/useArrayRef.js";
 import { isInboxSearchActive, } from "./state.js";
+function describeToolAvailability(availability) {
+    if (!availability) {
+        return "unknown";
+    }
+    if (availability.ok) {
+        return "available";
+    }
+    return `${availability.code}: ${availability.message}`;
+}
+function renderToolManifest(tools, toolAvailability) {
+    return tools
+        .map((tool) => {
+        const preconditions = tool.preconditions.length
+            ? tool.preconditions.join("; ")
+            : "none";
+        return `<item>${tool.name}: ${tool.description} | exposure=${tool.exposure} | availability=${describeToolAvailability(toolAvailability[tool.name])} | preconditions=${preconditions}</item>`;
+    })
+        .join("");
+}
 function InboxRootContent() {
     return (_jsxs(_Fragment, { children: [_jsx("text", { children: "App Navigation" }), _jsx("text", { children: "Semantic view graph" }), _jsx("item", { children: "Inbox: primary message list view." }), _jsx("item", { children: "Enter Inbox: mounted by default when the app opens." }), _jsx("item", { children: "Inbox actions: openMessage." }), _jsx("item", { children: "InboxSearch: focused search/results view for inbox queries." }), _jsx("item", { children: "Enter InboxSearch: use searchMessages when inbox search is relevant." }), _jsx("item", { children: "InboxSearch actions: searchMessages." }), _jsx("item", { children: "MessageDetail: opened message detail view." }), _jsx("item", { children: "Enter MessageDetail: use openMessage from Inbox." }), _jsx("item", { children: "MessageDetail actions: inspect the opened message state." })] }));
 }
@@ -33,14 +52,16 @@ function renderFragmentMarkup(children, collector) {
         markup: renderToString(_jsx(RefProvider, { registry: collector, children: children })),
     };
 }
-export function createInboxSnapshotBundle(state, visibleTools) {
+export function createInboxSnapshotBundle(state, tools, toolAvailability) {
     const collector = createRefCollector();
     const rootMarkup = renderFragmentMarkup(_jsx(InboxRootContent, {}), collector);
     const rootView = renderViewFragment({
         id: "root",
         type: "Root",
         name: "Navigation",
-        markup: rootMarkup.markup,
+        markup: rootMarkup.markup +
+            "<text>Tool manifest is stable; runtime validation decides whether a tool is currently executable.</text>" +
+            renderToolManifest(tools, toolAvailability),
     });
     const inboxMarkup = renderFragmentMarkup(_jsx(InboxListContent, { state: state }), collector);
     const mountedViews = [
@@ -73,6 +94,7 @@ export function createInboxSnapshotBundle(state, visibleTools) {
         rootView,
         mountedViews,
         refIndex: collector.snapshot(),
-        visibleTools,
+        tools,
+        toolAvailability,
     });
 }