glirastes 0.4.0 → 0.5.0

package/dist/cjs/sync/signature-verifier.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeRevisionVerifier = exports.RuntimeSyncVerificationError = void 0;
+exports.canonicalRuntimeJson = canonicalRuntimeJson;
+const node_crypto_1 = require("node:crypto");
+class RuntimeSyncVerificationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'RuntimeSyncVerificationError';
+    }
+}
+exports.RuntimeSyncVerificationError = RuntimeSyncVerificationError;
+function canonicalValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => (item === undefined ? null : canonicalValue(item)));
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => [key, canonicalValue(child)]));
+    }
+    return value;
+}
+function canonicalRuntimeJson(value) {
+    return JSON.stringify(canonicalValue(value));
+}
+class RuntimeRevisionVerifier {
+    keys;
+    constructor(keys) {
+        this.keys = keys;
+    }
+    async verifyRevision(revision) {
+        const actualHash = `sha256:${(0, node_crypto_1.createHash)('sha256')
+            .update(canonicalRuntimeJson(revision.payload))
+            .digest('base64url')}`;
+        if (actualHash !== revision.contentHash) {
+            throw new RuntimeSyncVerificationError('Runtime revision content hash does not match its payload', 'content_hash_mismatch');
+        }
+        const { signature, ...unsigned } = revision;
+        await this.verifyEnvelope(unsigned, signature);
+    }
+    /**
+     * A prompt bundle is content-addressed: its digest must match its canonical
+     * sections and its publisher signature must verify before anything downstream
+     * may parse or activate it.
+     */
+    async verifyPromptBundle(bundle) {
+        const actualDigest = `sha256:${(0, node_crypto_1.createHash)('sha256')
+            .update(canonicalRuntimeJson(bundle.sections))
+            .digest('base64url')}`;
+        if (actualDigest !== bundle.bundleDigest) {
+            throw new RuntimeSyncVerificationError('Prompt bundle digest does not match its sections', 'content_hash_mismatch');
+        }
+        const { signature, ...unsigned } = bundle;
+        await this.verifyEnvelope(unsigned, signature);
+    }
+    async verifyPromptBinding(binding) {
+        const { signature, ...unsigned } = binding;
+        await this.verifyEnvelope(unsigned, signature);
+    }
+    /**
+     * Verify any signed object of the `{ ...unsigned, signature }` envelope
+     * shape. Used by the standalone runtime source, whose locally
+     * materialized revisions must pass the same chain as managed ones.
+     */
+    async verifySignedObject(value) {
+        const { signature, ...unsigned } = value;
+        await this.verifyEnvelope(unsigned, signature);
+    }
+    async verifyRevocation(revocation) {
+        const { signature, ...unsigned } = revocation;
+        await this.verifyEnvelope(unsigned, signature);
+    }
+    async verifyExecutionLease(lease) {
+        const { signature, ...unsigned } = lease;
+        await this.verifyEnvelope(unsigned, signature);
+    }
+    async verifyEnvelope(unsigned, signature) {
+        const jwk = await this.keys.getKey(signature.keyId);
+        if (!jwk) {
+            throw new RuntimeSyncVerificationError(`Runtime signing key ${signature.keyId} is unavailable`, 'signing_key_unavailable');
+        }
+        let publicKey;
+        try {
+            publicKey = (0, node_crypto_1.createPublicKey)({ key: jwk, format: 'jwk' });
+            if (publicKey.asymmetricKeyType !== 'ed25519') {
+                throw new Error('not Ed25519');
+            }
+        }
+        catch {
+            throw new RuntimeSyncVerificationError('Runtime signing key is not a valid Ed25519 public key', 'invalid_signing_key');
+        }
+        const valid = (0, node_crypto_1.verify)(null, Buffer.from(canonicalRuntimeJson(unsigned)), publicKey, Buffer.from(signature.value, 'base64url'));
+        if (!valid) {
+            throw new RuntimeSyncVerificationError('Runtime revision signature is invalid', 'signature_invalid');
+        }
+    }
+}
+exports.RuntimeRevisionVerifier = RuntimeRevisionVerifier;

package/dist/cjs/sync/state-store.d.ts

@@ -0,0 +1,24 @@
+import { type RuntimeDeploymentBundle, type SecurityRevocation } from '../contracts/revisions.js';
+export interface RuntimeSyncState {
+    cursor: string | null;
+    stable: RuntimeDeploymentBundle | null;
+    canary: RuntimeDeploymentBundle | null;
+    pending: RuntimeDeploymentBundle[];
+    revocations: SecurityRevocation[];
+    updatedAt: string;
+}
+export interface RuntimeStateStore {
+    load(): Promise<RuntimeSyncState | null>;
+    saveAtomic(state: RuntimeSyncState): Promise<void>;
+}
+export declare class MemoryRuntimeStateStore implements RuntimeStateStore {
+    private state;
+    load(): Promise<RuntimeSyncState | null>;
+    saveAtomic(state: RuntimeSyncState): Promise<void>;
+}
+export declare class FileRuntimeStateStore implements RuntimeStateStore {
+    private readonly path;
+    constructor(path: string);
+    load(): Promise<RuntimeSyncState | null>;
+    saveAtomic(state: RuntimeSyncState): Promise<void>;
+}

package/dist/cjs/sync/state-store.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileRuntimeStateStore = exports.MemoryRuntimeStateStore = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const zod_1 = require("zod");
+const revisions_js_1 = require("../contracts/revisions.js");
+const RuntimeSyncStateSchema = zod_1.z.object({
+    cursor: zod_1.z.iso.datetime({ offset: true }).nullable(),
+    stable: revisions_js_1.RuntimeDeploymentBundleSchema.nullable(),
+    canary: revisions_js_1.RuntimeDeploymentBundleSchema.nullable(),
+    pending: zod_1.z.array(revisions_js_1.RuntimeDeploymentBundleSchema),
+    revocations: zod_1.z.array(revisions_js_1.SecurityRevocationSchema),
+    updatedAt: zod_1.z.iso.datetime({ offset: true }),
+}).strict();
+class MemoryRuntimeStateStore {
+    state = null;
+    async load() {
+        return this.state ? structuredClone(this.state) : null;
+    }
+    async saveAtomic(state) {
+        this.state = structuredClone(RuntimeSyncStateSchema.parse(state));
+    }
+}
+exports.MemoryRuntimeStateStore = MemoryRuntimeStateStore;
+class FileRuntimeStateStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async load() {
+        let serialized;
+        try {
+            serialized = await (0, promises_1.readFile)(this.path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        return RuntimeSyncStateSchema.parse(JSON.parse(serialized));
+    }
+    async saveAtomic(state) {
+        const validated = RuntimeSyncStateSchema.parse(state);
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(this.path), { recursive: true });
+        const temporaryPath = `${this.path}.${process.pid}.tmp`;
+        await (0, promises_1.writeFile)(temporaryPath, `${JSON.stringify(validated)}\n`, { encoding: 'utf8', mode: 0o600 });
+        await (0, promises_1.rename)(temporaryPath, this.path);
+    }
+}
+exports.FileRuntimeStateStore = FileRuntimeStateStore;

package/dist/cjs/sync/sync-manager.d.ts

@@ -0,0 +1,27 @@
+import { type RuntimeDeploymentBundle, type SecurityRevocation } from '../contracts/revisions.js';
+import type { RuntimeRevisionVerifier } from './signature-verifier.js';
+import { type RuntimeStateStore, type RuntimeSyncState } from './state-store.js';
+import type { MaterializedDeploymentRevisions } from './materialize-deployment.js';
+export interface RuntimeSyncApplyResult {
+    state: RuntimeSyncState;
+    rejectedDeploymentIds: string[];
+    rejectedRevocationIds: string[];
+}
+export declare class RuntimeSyncManager {
+    private readonly options;
+    constructor(options: {
+        environmentId: string;
+        store: RuntimeStateStore;
+        verifier: RuntimeRevisionVerifier;
+        validateDeployment?: (deployment: RuntimeDeploymentBundle, revisions: MaterializedDeploymentRevisions) => void | Promise<void>;
+        onRevocations?: (revocations: SecurityRevocation[]) => void | Promise<void>;
+        onPending?: (deployments: RuntimeDeploymentBundle[]) => void | Promise<void>;
+        onActivated?: (deployments: RuntimeDeploymentBundle[]) => void | Promise<void>;
+    });
+    apply(rawBundle: unknown): Promise<RuntimeSyncApplyResult>;
+    private deploymentScopeMatches;
+    private latest;
+    private mergePending;
+    private objectId;
+    private emptyState;
+}

package/dist/cjs/sync/sync-manager.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeSyncManager = void 0;
+const zod_1 = require("zod");
+const revisions_js_1 = require("../contracts/revisions.js");
+const materialize_deployment_js_1 = require("./materialize-deployment.js");
+const WireSyncBundleSchema = zod_1.z.object({
+    cursor: zod_1.z.iso.datetime({ offset: true }),
+    activeSnapshotComplete: zod_1.z.literal(true),
+    deployments: zod_1.z.array(zod_1.z.unknown()),
+    revocations: zod_1.z.array(zod_1.z.unknown()),
+}).strict();
+class RuntimeSyncManager {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async apply(rawBundle) {
+        const wire = WireSyncBundleSchema.parse(rawBundle);
+        let state = await this.options.store.load() ?? this.emptyState();
+        const rejectedRevocationIds = [];
+        const acceptedRevocations = [];
+        for (const rawRevocation of wire.revocations) {
+            const parsed = revisions_js_1.SecurityRevocationSchema.safeParse(rawRevocation);
+            const id = this.objectId(rawRevocation, 'revocationId');
+            if (!parsed.success
+                || parsed.data.environmentId !== this.options.environmentId) {
+                rejectedRevocationIds.push(id);
+                continue;
+            }
+            try {
+                await this.options.verifier.verifyRevocation(parsed.data);
+                acceptedRevocations.push(parsed.data);
+            }
+            catch {
+                rejectedRevocationIds.push(parsed.data.revocationId);
+            }
+        }
+        if (acceptedRevocations.length > 0) {
+            const byId = new Map(state.revocations.map((revocation) => [revocation.revocationId, revocation]));
+            for (const revocation of acceptedRevocations) {
+                byId.set(revocation.revocationId, revocation);
+            }
+            state = {
+                ...state,
+                revocations: [...byId.values()],
+                updatedAt: wire.cursor,
+            };
+            // Persist revocations before candidate processing. A crash may replay the
+            // same cursor, but revocation IDs make that replay idempotent.
+            await this.options.store.saveAtomic(state);
+            await this.options.onRevocations?.(acceptedRevocations);
+        }
+        const acceptedDeployments = [];
+        const rejectedDeploymentIds = [];
+        let rejectedActive = false;
+        let rejectedPending = false;
+        for (const rawDeployment of wire.deployments) {
+            const parsed = revisions_js_1.RuntimeDeploymentBundleSchema.safeParse(rawDeployment);
+            const id = this.objectId(rawDeployment, 'deploymentId');
+            const rawStatus = (rawDeployment
+                && typeof rawDeployment === 'object'
+                && 'status' in rawDeployment) ? rawDeployment.status : undefined;
+            if (!parsed.success
+                || !this.deploymentScopeMatches(parsed.data)) {
+                rejectedDeploymentIds.push(id);
+                if (rawStatus === 'active')
+                    rejectedActive = true;
+                else
+                    rejectedPending = true;
+                continue;
+            }
+            try {
+                await this.options.verifier.verifyRevision(parsed.data.agentRevision);
+                await this.options.verifier.verifyRevision(parsed.data.manifestRevision);
+                await this.options.verifier.verifyRevision(parsed.data.policyRevision);
+                // Artifact bindings are signed material like the three revisions above;
+                // accepting them unverified would smuggle unsigned desired state into
+                // the fail-closed path.
+                if (parsed.data.configRevision) {
+                    await this.options.verifier.verifyRevision(parsed.data.configRevision);
+                }
+                if (parsed.data.promptBinding) {
+                    await this.options.verifier.verifyPromptBinding(parsed.data.promptBinding);
+                }
+                const materialized = (0, materialize_deployment_js_1.materializeDeploymentRevisions)(parsed.data);
+                await this.options.validateDeployment?.(parsed.data, materialized);
+                acceptedDeployments.push(parsed.data);
+            }
+            catch {
+                rejectedDeploymentIds.push(parsed.data.deploymentId);
+                if (parsed.data.status === 'active')
+                    rejectedActive = true;
+                else
+                    rejectedPending = true;
+            }
+        }
+        const active = acceptedDeployments.filter((deployment) => deployment.status === 'active');
+        const pending = acceptedDeployments.filter((deployment) => deployment.status === 'pending');
+        if (!rejectedActive && wire.activeSnapshotComplete) {
+            state = {
+                ...state,
+                stable: this.latest(active, 'stable'),
+                canary: this.latest(active, 'canary'),
+            };
+        }
+        const activeIds = new Set(active.map((deployment) => deployment.deploymentId));
+        const nextPending = (rejectedPending
+            ? this.mergePending(state.pending, pending)
+            : pending).filter((deployment) => !activeIds.has(deployment.deploymentId));
+        state = {
+            ...state,
+            pending: nextPending,
+            cursor: wire.cursor,
+            updatedAt: wire.cursor,
+        };
+        await this.options.store.saveAtomic(state);
+        if (pending.length > 0)
+            await this.options.onPending?.(pending);
+        if (active.length > 0 && !rejectedActive) {
+            await this.options.onActivated?.(active);
+        }
+        return { state, rejectedDeploymentIds, rejectedRevocationIds };
+    }
+    deploymentScopeMatches(deployment) {
+        const revisions = [
+            deployment.agentRevision,
+            deployment.manifestRevision,
+            deployment.policyRevision,
+        ];
+        const first = revisions[0];
+        return deployment.environmentId === this.options.environmentId
+            && deployment.manifestRevision.environmentId === this.options.environmentId
+            && deployment.policyRevision.environmentId === this.options.environmentId
+            && revisions.every((revision) => (revision.tenantId === first.tenantId
+                && revision.targetAppId === first.targetAppId));
+    }
+    latest(deployments, mode) {
+        return deployments
+            .filter((deployment) => deployment.rolloutMode === mode)
+            .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))[0]
+            ?? null;
+    }
+    mergePending(current, accepted) {
+        const byId = new Map(current.map((deployment) => [
+            deployment.deploymentId,
+            deployment,
+        ]));
+        for (const deployment of accepted)
+            byId.set(deployment.deploymentId, deployment);
+        return [...byId.values()];
+    }
+    objectId(value, key) {
+        if (value
+            && typeof value === 'object'
+            && key in value
+            && typeof value[key] === 'string') {
+            return value[key];
+        }
+        return 'unknown';
+    }
+    emptyState() {
+        return {
+            cursor: null,
+            stable: null,
+            canary: null,
+            pending: [],
+            revocations: [],
+            updatedAt: new Date(0).toISOString(),
+        };
+    }
+}
+exports.RuntimeSyncManager = RuntimeSyncManager;

package/dist/cjs/types.d.ts

@@ -1,5 +1,38 @@
-import { z } from 'zod';
-export type EndpointMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+export interface SchemaIssueLike {
+    path?: ReadonlyArray<PropertyKey>;
+    message?: string;
+}
+export interface SchemaErrorLike {
+    issues: ReadonlyArray<SchemaIssueLike>;
+}
+export type SafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: SchemaErrorLike;
+};
+/**
+ * Minimal runtime schema contract accepted at public Glirastes boundaries.
+ *
+ * Keeping this structural avoids coupling target applications to the SDK's
+ * own Zod major. Zod 3, Zod 4, and Standard-Schema-compatible adapters all
+ * satisfy it without conversion.
+ */
+export interface SchemaLike<T = unknown> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: SchemaErrorLike;
+    };
+    readonly ['~standard']?: unknown;
+}
+export type InferSchema<TSchema> = TSchema extends {
+    readonly _output: infer TOutput;
+} ? TOutput : TSchema extends SchemaLike<infer TOutput> ? TOutput : unknown;
+export type EndpointMethod = 'GET' | 'HEAD' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
 /**
  * Runtime context for tool execution (transport-level info).
  * Used so tools can forward the caller's auth (cookies, origin) to backend APIs.
@@ -9,6 +42,11 @@ export type EndpointMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
 export interface RuntimeContext {
     origin?: string;
     cookieHeader?: string;
+    /**
+     * Client actions with a handler on the page the user has open, as the chat
+     * reported them. Absent when the client does not report them.
+     */
+    clientActions?: readonly string[];
     [key: string]: unknown;
 }
 /**
@@ -29,10 +67,10 @@ export interface Tool {
     id: string;
     /** Human-readable description for AI to understand when to use this */
     description: string;
-    /** Zod schema for input validation — shared between AI and API */
-    inputSchema: z.ZodType;
-    /** Optional Zod schema describing the tool's response shape */
-    outputSchema?: z.ZodType;
+    /** Host-provided runtime schema for input validation */
+    inputSchema: SchemaLike;
+    /** Optional host-provided schema describing the tool's response shape */
+    outputSchema?: SchemaLike;
     /** HTTP method of the underlying endpoint (e.g. GET, POST). Used by test suites to derive approval defaults. */
     method?: string;
     /**
@@ -46,15 +84,15 @@ export interface Tool {
 /**
  * Helper to define a tool with full type inference at definition site.
  */
-export declare function defineTool<TInput extends z.ZodType, TOutput>(tool: {
+export declare function defineTool<TInput extends SchemaLike, TOutput>(tool: {
     id: string;
     description: string;
     inputSchema: TInput;
-    outputSchema?: z.ZodType<TOutput>;
+    outputSchema?: SchemaLike<TOutput>;
     method?: string;
     /** @deprecated Use Glirastes approval flows via `lancer.approvals` instead. Kept for backward compatibility. */
-    needsApproval?: boolean | ((input: z.infer<TInput>, context: ToolContext) => boolean | Promise<boolean>);
-    execute: (input: z.infer<TInput>, context: ToolContext) => Promise<TOutput>;
+    needsApproval?: boolean | ((input: InferSchema<TInput>, context: ToolContext) => boolean | Promise<boolean>);
+    execute: (input: InferSchema<TInput>, context: ToolContext) => Promise<TOutput>;
 }): Tool;
 /**
  * Registry of all tools in the system.
@@ -76,7 +114,7 @@ export interface UiActionTemplate {
  *
  * @param extraSchemas - Additional Zod schemas for app-specific action types
  */
-export declare function createUiActionSchema(extraSchemas?: z.ZodTypeAny[]): z.ZodUnion<[z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, ...z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[]]>;
+export declare function createUiActionSchema(extraSchemas?: SchemaLike<Record<string, unknown>>[]): SchemaLike<Record<string, unknown>>;
 export type UiPatternType = 'filter-and-navigate' | 'open-detail' | 'open-dialog' | 'refresh' | 'toast';
 export interface FilterAndNavigatePattern {
     type: 'filter-and-navigate';
@@ -116,7 +154,7 @@ export interface ToastPattern {
     variant?: 'default' | 'success' | 'error' | 'warning';
 }
 export type UiPattern = FilterAndNavigatePattern | OpenDetailPattern | OpenDialogPattern | RefreshPattern | ToastPattern;
-export interface AiEndpointToolDefinition<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> {
+export interface AiEndpointToolDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> {
     id: string;
     toolName: string;
     /** Which intent module this tool belongs to */
@@ -132,6 +170,11 @@ export interface AiEndpointToolDefinition<TInput extends z.ZodTypeAny = z.ZodTyp
      * When provided, a compact description is auto-appended to the tool description.
      */
     outputSchema?: TOutput;
+    /**
+     * Legacy discovery hint migrated into the signed runtime policy.
+     * It is never sufficient authorization for local tool execution.
+     */
+    allowedRoles?: string[];
     /** @deprecated Use Glirastes approval flows via `lancer.approvals` instead. Kept for backward compatibility. */
     needsApproval?: boolean;
     /**
@@ -147,8 +190,8 @@ export interface AiEndpointToolDefinition<TInput extends z.ZodTypeAny = z.ZodTyp
      */
     uiPattern?: UiPattern | UiPattern[];
 }
-export declare function defineEndpointTool<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny>(definition: AiEndpointToolDefinition<TInput, TOutput>): AiEndpointToolDefinition<TInput, TOutput>;
-export interface AiUiToolDefinition<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> {
+export declare function defineEndpointTool<TInput extends SchemaLike, TOutput extends SchemaLike = SchemaLike>(definition: AiEndpointToolDefinition<TInput, TOutput>): AiEndpointToolDefinition<TInput, TOutput>;
+export interface AiUiToolDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> {
     id: string;
     toolName: string;
     /** Which intent module this tool belongs to */
@@ -162,6 +205,11 @@ export interface AiUiToolDefinition<TInput extends z.ZodTypeAny = z.ZodTypeAny,
      * When provided, a compact description is auto-appended to the tool description.
      */
     outputSchema?: TOutput;
+    /**
+     * Legacy discovery hint migrated into the signed runtime policy.
+     * It is never sufficient authorization for local UI action execution.
+     */
+    allowedRoles?: string[];
     /** @deprecated Use Glirastes approval flows via `lancer.approvals` instead. Kept for backward compatibility. */
     needsApproval?: boolean;
     successMessage?: string;
@@ -176,7 +224,7 @@ export interface AiUiToolDefinition<TInput extends z.ZodTypeAny = z.ZodTypeAny,
      */
     uiPattern?: UiPattern | UiPattern[];
 }
-export declare function defineUiTool<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny>(definition: AiUiToolDefinition<TInput, TOutput>): AiUiToolDefinition<TInput, TOutput>;
+export declare function defineUiTool<TInput extends SchemaLike, TOutput extends SchemaLike = SchemaLike>(definition: AiUiToolDefinition<TInput, TOutput>): AiUiToolDefinition<TInput, TOutput>;
 /**
  * Model tier for selecting appropriate model based on task complexity.
  * - fast: Quick responses, simple lookups
@@ -404,6 +452,8 @@ export interface PromptOverride {
 export declare function applyPromptOverride(base: string, override: PromptOverride): string;
 export interface AiRouterConfig {
     modules: ModuleDefinition[];
+    /** Focused routing avoids full-catalogue fallbacks; direct routers retain legacy defaults. */
+    routingMode?: 'focused' | 'legacy';
     expansionStrategy?: 'minimal' | 'shared' | 'full';
     relatedModules?: Record<string, string[]>;
     confidenceThresholds?: {
@@ -414,7 +464,7 @@ export interface AiRouterConfig {
 export interface SelectedTools {
     tools: string[];
     module: ModuleDefinition | null;
-    strategy: 'single' | 'expanded' | 'all';
+    strategy: 'single' | 'expanded' | 'all' | 'none';
 }
 export interface AiRouter {
     route(intent: IntentClassification, allToolNames: string[]): SelectedTools;
@@ -554,6 +604,8 @@ export interface AiPipelineConfig {
 export interface PipelineResult {
     model: ModelConfig;
     tools: string[];
+    /** Honor this exact selection, including zero tools. Omit for legacy empty-means-all behavior. */
+    toolSelection?: 'explicit';
     sanitizedInput: string;
     intent: IntentClassification;
     module: ModuleDefinition | null;

package/dist/cjs/types.js

@@ -51,12 +51,40 @@ function createUiActionSchema(extraSchemas = []) {
         return (typeof id === 'string' &&
             /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id));
     }, { message: 'Entity action must include valid {entity}Id (UUID)' });
-    return zod_1.z.union([
+    // Results of the generated UI tools (`ui.navigate`, `ui.filter.<view>`,
+    // `ui.<actionId>`). The browser bridge checks the href again, and the app's
+    // contract checks a client action payload when it is dispatched.
+    const generatedNavigateSchema = zod_1.z
+        .object({
+        type: zod_1.z.literal('glirastes.navigate'),
+        actionId: zod_1.z.literal('glirastes.navigate'),
+        payload: zod_1.z.object({ href: zod_1.z.string().startsWith('/').max(2_048) }).passthrough(),
+    })
+        .strict();
+    const generatedClientActionSchema = zod_1.z
+        .object({
+        type: zod_1.z.literal('glirastes.action'),
+        actionId: zod_1.z.string().min(1).max(200),
+        payload: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    })
+        .strict();
+    const builtInSchema = zod_1.z.union([
         runClientActionSchema,
         navigateSchema,
-        ...extraSchemas,
+        generatedNavigateSchema,
+        generatedClientActionSchema,
         entityActionSchema, // Fallback — must be last
     ]);
+    return {
+        safeParse(value) {
+            for (const schema of extraSchemas) {
+                const result = schema.safeParse(value);
+                if (result.success)
+                    return result;
+            }
+            return builtInSchema.safeParse(value);
+        },
+    };
 }
 function defineEndpointTool(definition) {
     return definition;

package/dist/cli/bin.js

@@ -2,33 +2,44 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { runCli } from './index.js';
-// Load .env and .env.local files (more specific wins)
-for (const envFile of ['.env', '.env.local']) {
-    try {
-        const content = readFileSync(resolve(process.cwd(), envFile), 'utf-8');
-        for (const line of content.split('\n')) {
-            const trimmed = line.trim();
-            if (!trimmed || trimmed.startsWith('#'))
-                continue;
-            const eqIndex = trimmed.indexOf('=');
-            if (eqIndex < 0)
-                continue;
-            const key = trimmed.slice(0, eqIndex).trim();
-            const raw = trimmed.slice(eqIndex + 1).trim();
-            // Strip surrounding quotes
-            const value = raw.replace(/^["']|["']$/g, '');
-            // Don't override existing env vars
-            if (!(key in process.env)) {
-                process.env[key] = value;
+import { foundationDiagnosticJson, isFoundationDiagnosticError, } from '../diagnostics/index.js';
+import { shouldLoadImplicitEnvironment } from './environment-loading.js';
+const cliArgs = process.argv.slice(2);
+if (shouldLoadImplicitEnvironment(cliArgs)) {
+    // Transitional commands retain their existing implicit dotenv behavior.
+    for (const envFile of ['.env', '.env.local']) {
+        try {
+            const content = readFileSync(resolve(process.cwd(), envFile), 'utf-8');
+            for (const line of content.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#'))
+                    continue;
+                const eqIndex = trimmed.indexOf('=');
+                if (eqIndex < 0)
+                    continue;
+                const key = trimmed.slice(0, eqIndex).trim();
+                const raw = trimmed.slice(eqIndex + 1).trim();
+                const value = raw.replace(/^["']|["']$/g, '');
+                if (!(key in process.env)) {
+                    process.env[key] = value;
+                }
             }
         }
-    }
-    catch {
-        // File doesn't exist — skip
+        catch {
+            // File doesn't exist — skip
+        }
     }
 }
-runCli(process.argv.slice(2)).catch((error) => {
-    console.error(error instanceof Error ? error.message : error);
+runCli(cliArgs).catch((error) => {
+    if (process.argv.includes('--json')) {
+        console.log(JSON.stringify(foundationDiagnosticJson(error, 'cli')));
+    }
+    else if (isFoundationDiagnosticError(error)) {
+        console.error(`${error.code}: ${error.message}`);
+    }
+    else {
+        console.error('E-SETUP-999: Glirastes command failed.');
+    }
     process.exit(1);
 });
 //# sourceMappingURL=bin.js.map