@appmind/core 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AppMind contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @appmind/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AppMind core runtime: agent orchestration, UI context, action registry, and provider interfaces.
+
+Part of [AppMind](https://github.com/dmitripoli/appmind) — a local-first, drop-in AI copilot for web apps. See the main README for setup and concepts.
+
+```bash
+npm install @appmind/core
+```
+
+License: MIT

package/dist/actions.d.ts

@@ -0,0 +1,40 @@
+import type { AppMindContext } from "./context.js";
+export type ActionRisk = "read" | "low" | "medium" | "high";
+/**
+ * An operation the application explicitly exposes to the AI (PRD §32–34).
+ * The model may only ever request registered actions; it can never execute
+ * application code directly.
+ */
+export interface AppMindAction<TInput = unknown, TResult = unknown> {
+    name: string;
+    description: string;
+    /**
+     * A JSON-schema-like description of the parameters. Bring your own validator
+     * (e.g. a zod schema exposes `.parse`); AppMind treats it as opaque here and
+     * only requires the shape to be describable to the model.
+     */
+    parameters?: unknown;
+    risk?: ActionRisk;
+    requiresConfirmation?: boolean;
+    /** Hide the action from the model when it isn't applicable to the context. */
+    isAvailable?: (context: AppMindContext) => boolean;
+    execute: (input: TInput, context: AppMindContext) => Promise<TResult>;
+}
+/** A validated, model-requested action awaiting execution/confirmation. */
+export interface PendingAction {
+    name: string;
+    input: unknown;
+    risk: ActionRisk;
+    requiresConfirmation: boolean;
+}
+export declare class ActionRegistry {
+    private actions;
+    register(action: AppMindAction<any, any>): () => void;
+    unregister(name: string): void;
+    get(name: string): AppMindAction<any, any> | undefined;
+    /** Only the actions currently applicable to the context (PRD §37). */
+    available(context: AppMindContext): AppMindAction<any, any>[];
+    /** Confirmation policy: destructive/high-risk always confirms (PRD §34–35). */
+    static needsConfirmation(action: AppMindAction<any, any>): boolean;
+}
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;IACnD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvE;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAA8C;IAE7D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,IAAI;IAUrD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS;IAItD,sEAAsE;IACtE,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE;IAI7D,+EAA+E;IAC/E,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,OAAO;CAInE"}

package/dist/actions.js

@@ -0,0 +1,32 @@
+export class ActionRegistry {
+    constructor() {
+        this.actions = new Map();
+    }
+    register(action) {
+        this.actions.set(action.name, action);
+        // Only remove what *this* call registered: a stale disposer (e.g. React
+        // StrictMode's discarded first effect, or an MCP connection torn down after
+        // a reconnect) must not delete a newer registration under the same name.
+        return () => {
+            if (this.actions.get(action.name) === action)
+                this.actions.delete(action.name);
+        };
+    }
+    unregister(name) {
+        this.actions.delete(name);
+    }
+    get(name) {
+        return this.actions.get(name);
+    }
+    /** Only the actions currently applicable to the context (PRD §37). */
+    available(context) {
+        return [...this.actions.values()].filter((a) => !a.isAvailable || a.isAvailable(context));
+    }
+    /** Confirmation policy: destructive/high-risk always confirms (PRD §34–35). */
+    static needsConfirmation(action) {
+        if (action.requiresConfirmation !== undefined)
+            return action.requiresConfirmation;
+        return action.risk === "high" || action.risk === "medium";
+    }
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAiCA,MAAM,OAAO,cAAc;IAA3B;QACU,YAAO,GAAG,IAAI,GAAG,EAAmC,CAAC;IA8B/D,CAAC;IA5BC,QAAQ,CAAC,MAA+B;QACtC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,wEAAwE;QACxE,4EAA4E;QAC5E,yEAAyE;QACzE,OAAO,GAAG,EAAE;YACV,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,MAAM;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACjF,CAAC,CAAC;IACJ,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,sEAAsE;IACtE,SAAS,CAAC,OAAuB;QAC/B,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5F,CAAC;IAED,+EAA+E;IAC/E,MAAM,CAAC,iBAAiB,CAAC,MAA+B;QACtD,IAAI,MAAM,CAAC,oBAAoB,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC,oBAAoB,CAAC;QAClF,OAAO,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC;IAC5D,CAAC;CACF"}

package/dist/appmind.d.ts

@@ -0,0 +1,109 @@
+import { type Embedder, type KnowledgeIndex, type RetrievalResult, type RetrievalWeights } from "@appmind/knowledge";
+import { type AppMindAction, type PendingAction } from "./actions.js";
+import { type AppMindContext } from "./context.js";
+import { type AppMindEvents, type EventName } from "./events.js";
+import type { AppMindModelProvider, ChatMessage, ModelLocation } from "./model.js";
+import { type AppMindStorage } from "./storage.js";
+import { type PromptBudget } from "./runtime.js";
+export interface AppMindConfig {
+    knowledge: {
+        manifest: string;
+        index?: never;
+    } | {
+        index: KnowledgeIndex;
+        manifest?: never;
+    };
+    model?: AppMindModelProvider;
+    storage?: AppMindStorage;
+    /**
+     * Query embedder. If omitted, one is derived from the loaded manifest's
+     * `embeddingModel` so the runtime query vectors automatically match the index.
+     */
+    embedder?: Embedder;
+    retrieval?: {
+        topK?: number;
+        weights?: Partial<RetrievalWeights>;
+    };
+    /** Prompt token budget (defaults target a ~4K-token prompt) and optional `countTokens`. */
+    prompt?: Partial<PromptBudget>;
+    /**
+     * Called before executing an action that requires confirmation (PRD §35).
+     * Must resolve true to proceed. If omitted, confirmation-required actions are
+     * denied by default (fail closed).
+     */
+    onConfirm?: (pending: PendingAction) => Promise<boolean>;
+    /** How to fetch remote resources (manifest/index). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/** High-level events streamed from a chat turn. */
+export type ChatEvent = {
+    type: "sources";
+    sources: RetrievalResult[];
+} | {
+    type: "text";
+    delta: string;
+} | {
+    type: "action_pending";
+    action: PendingAction;
+} | {
+    type: "action_result";
+    name: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+} | {
+    type: "location";
+    location: ModelLocation;
+} | {
+    type: "done";
+} | {
+    type: "error";
+    error: string;
+};
+export interface ChatOptions {
+    history?: ChatMessage[];
+    signal?: AbortSignal;
+}
+export declare class AppMind {
+    private readonly config;
+    private readonly ctx;
+    private readonly registry;
+    private readonly emitter;
+    private readonly storage;
+    private readonly fetchFn;
+    private index;
+    private embedder;
+    private started;
+    private confirmHandler;
+    constructor(config: AppMindConfig);
+    /**
+     * Set/replace the confirmation handler at runtime. The React provider uses
+     * this to drive its confirmation UI. Returns a disposer that restores the
+     * previous handler.
+     */
+    setConfirmationHandler(handler: (pending: PendingAction) => Promise<boolean>): () => void;
+    /** Load the knowledge index (from cache or CDN) and initialize the model. */
+    start(): Promise<void>;
+    setContext(context: AppMindContext): void;
+    mergeContext(patch: Partial<AppMindContext>): void;
+    getContext(): AppMindContext;
+    registerAction<TInput, TResult>(action: AppMindAction<TInput, TResult>): () => void;
+    search(query: string, options?: {
+        limit?: number;
+    }): Promise<RetrievalResult[]>;
+    chat(message: string, options?: ChatOptions): AsyncIterable<ChatEvent>;
+    /**
+     * One follow-up generation that answers the user from an action's result.
+     * No tools are offered (and any tool call is ignored), so it can't loop. The
+     * result goes in as a plain user-role message — portable across providers
+     * that lack native tool-result messages.
+     */
+    private answerFromResult;
+    private runAction;
+    /** Which engine the next chat turn will use (PRD §54 privacy API). */
+    modelLocation(): ModelLocation | undefined;
+    on<K extends EventName>(name: K, handler: (payload: AppMindEvents[K]) => void): () => void;
+    dispose(): Promise<void>;
+    private loadIndex;
+}
+//# sourceMappingURL=appmind.d.ts.map

package/dist/appmind.d.ts.map

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

package/dist/appmind.js

@@ -0,0 +1,306 @@
+import { assertEmbedderCompatible, createEmbedder, CURRENT_INDEX_SCHEMA, retrieve, } from "@appmind/knowledge";
+import { ActionRegistry } from "./actions.js";
+import { ContextStore } from "./context.js";
+import { Emitter } from "./events.js";
+import { MemoryStorage } from "./storage.js";
+import { buildSystemPrompt, DEFAULT_PROMPT_BUDGET, estimateTokens, parseToolCallFromText, toToolSpecs, windowHistory, } from "./runtime.js";
+export class AppMind {
+    constructor(config) {
+        this.ctx = new ContextStore();
+        this.registry = new ActionRegistry();
+        this.emitter = new Emitter();
+        this.started = false;
+        this.config = config;
+        this.storage = config.storage ?? new MemoryStorage();
+        // Wrap (don't reference) the global fetch: a bare `globalThis.fetch` called
+        // as a method throws "Illegal invocation" because it loses its Window `this`.
+        this.fetchFn = config.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.confirmHandler = config.onConfirm;
+    }
+    /**
+     * Set/replace the confirmation handler at runtime. The React provider uses
+     * this to drive its confirmation UI. Returns a disposer that restores the
+     * previous handler.
+     */
+    setConfirmationHandler(handler) {
+        const prev = this.confirmHandler;
+        this.confirmHandler = handler;
+        return () => {
+            this.confirmHandler = prev;
+        };
+    }
+    /** Load the knowledge index (from cache or CDN) and initialize the model. */
+    async start() {
+        if (this.started)
+            return;
+        this.index = await this.loadIndex();
+        // Guard against an index format this runtime can't read (PRD §25).
+        const schema = this.index.manifest.schemaVersion ?? 1;
+        if (schema > CURRENT_INDEX_SCHEMA) {
+            throw new Error(`AppMind index schema v${schema} is newer than this runtime supports (v${CURRENT_INDEX_SCHEMA}). Upgrade @appmind/core.`);
+        }
+        // Derive the query embedder from the manifest unless the app supplied one,
+        // guaranteeing the query vector space matches the index's document vectors.
+        this.embedder =
+            this.config.embedder ??
+                createEmbedder({
+                    id: this.index.manifest.embeddingModel,
+                    dimensions: this.index.manifest.dimensions,
+                });
+        // Fail closed if a supplied embedder doesn't match the index's vector space.
+        assertEmbedderCompatible(this.index.manifest, this.embedder);
+        if (this.config.model) {
+            this.emitter.emit("model_loading", { provider: this.config.model.id });
+            await this.config.model.initialize();
+            this.emitter.emit("model_ready", {
+                provider: this.config.model.id,
+                location: this.config.model.location(),
+            });
+        }
+        this.started = true;
+        this.emitter.emit("initialized", undefined);
+    }
+    // --- Context (PRD §29) ---
+    setContext(context) {
+        this.ctx.set(context);
+    }
+    mergeContext(patch) {
+        this.ctx.merge(patch);
+    }
+    getContext() {
+        return this.ctx.get();
+    }
+    // --- Actions (PRD §32) ---
+    registerAction(action) {
+        return this.registry.register(action);
+    }
+    // --- Knowledge search (PRD §28) ---
+    async search(query, options = {}) {
+        if (!this.index || !this.embedder)
+            throw new Error("AppMind not started: call start() first.");
+        const started = now();
+        const queryEmbedding = await this.embedder.embed(query);
+        const results = retrieve(queryEmbedding, query, this.index.chunks, {
+            limit: options.limit ?? this.config.retrieval?.topK ?? 5,
+            weights: this.config.retrieval?.weights,
+            context: {
+                route: this.ctx.get().route,
+                resourceType: this.ctx.get().resource?.type,
+                keywords: this.ctx.keywords(),
+            },
+        });
+        this.emitter.emit("retrieval", { count: results.length, latencyMs: now() - started });
+        return results;
+    }
+    // --- Chat / agent runtime (PRD §39) ---
+    async *chat(message, options = {}) {
+        if (!this.config.model) {
+            yield { type: "error", error: "No model provider configured." };
+            return;
+        }
+        if (!this.index) {
+            yield { type: "error", error: "AppMind not started: call start() first." };
+            return;
+        }
+        this.emitter.emit("query", { text: message });
+        // 1. Retrieve relevant knowledge + expose only applicable actions.
+        const sources = await this.search(message, {
+            limit: this.config.retrieval?.topK ?? 5,
+        });
+        yield { type: "sources", sources };
+        const actions = this.registry.available(this.ctx.get());
+        // Budget the prompt: window history, then fill knowledge with the remainder.
+        const budget = { ...DEFAULT_PROMPT_BUDGET, ...this.config.prompt };
+        const count = budget.countTokens ?? estimateTokens;
+        const history = windowHistory(options.history ?? [], budget.maxHistoryTurns);
+        const usedTokens = count(message) + history.reduce((s, m) => s + count(m.content), 0);
+        const system = buildSystemPrompt(this.ctx.toPromptBlock(), sources, actions, {
+            budget: this.config.prompt,
+            usedTokens,
+        });
+        const model = this.config.model;
+        yield { type: "location", location: model.location() };
+        this.emitter.emit("generation", { location: model.location() });
+        // 2. Generate. Accumulate text to detect text-encoded tool calls.
+        let fullText = "";
+        let structuredTool;
+        try {
+            for await (const ev of model.generate({
+                system,
+                messages: [...history, { role: "user", content: message }],
+                tools: toToolSpecs(actions),
+                signal: options.signal,
+            })) {
+                if (ev.type === "text") {
+                    fullText += ev.delta;
+                    yield { type: "text", delta: ev.delta };
+                }
+                else if (ev.type === "tool_call") {
+                    structuredTool = { name: ev.name, arguments: ev.arguments };
+                }
+                else if (ev.type === "error") {
+                    this.emitter.emit("error", { error: ev.error });
+                    yield { type: "error", error: ev.error };
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            this.emitter.emit("error", { error });
+            yield { type: "error", error };
+            return;
+        }
+        // 3. Resolve a tool call. A structured tool_call is trusted; a tool call
+        //    merely parsed out of the text is honored ONLY when it names a real
+        //    registered action — otherwise it's a hallucination and we keep the
+        //    model's text as the answer.
+        let toolCall = structuredTool;
+        if (!toolCall) {
+            const parsed = parseToolCallFromText(fullText);
+            if (parsed && this.registry.get(parsed.name))
+                toolCall = parsed;
+        }
+        if (toolCall) {
+            let result;
+            for await (const ev of this.runAction(toolCall.name, toolCall.arguments)) {
+                if (ev.type === "action_result")
+                    result = ev;
+                yield ev;
+            }
+            // 4. Hand a successful result back to the model for one answer turn, so
+            //    "what's the ARV?" ends with the number, not just "✓ completed".
+            if (result?.ok) {
+                yield* this.answerFromResult(model, system, [...history, { role: "user", content: message }], toolCall, result.result, options.signal);
+            }
+        }
+        yield { type: "done" };
+    }
+    /**
+     * One follow-up generation that answers the user from an action's result.
+     * No tools are offered (and any tool call is ignored), so it can't loop. The
+     * result goes in as a plain user-role message — portable across providers
+     * that lack native tool-result messages.
+     */
+    async *answerFromResult(model, system, messages, call, result, signal) {
+        const serialized = truncate(typeof result === "string" ? result : JSON.stringify(result ?? null), MAX_RESULT_CHARS);
+        let first = true;
+        try {
+            for await (const ev of model.generate({
+                system,
+                messages: [
+                    ...messages,
+                    { role: "assistant", content: `Called ${call.name} with ${JSON.stringify(call.arguments ?? {})}.` },
+                    {
+                        role: "user",
+                        content: `Result of ${call.name}:\n${serialized}\n\n` +
+                            "Answer my previous question using this result. Do not call any action.",
+                    },
+                ],
+                tools: [],
+                signal,
+            })) {
+                if (ev.type === "text") {
+                    yield { type: "text", delta: first ? `\n\n${ev.delta.trimStart()}` : ev.delta };
+                    first = false;
+                }
+                else if (ev.type === "error") {
+                    this.emitter.emit("error", { error: ev.error });
+                    return; // the action already succeeded; a missing summary isn't fatal
+                }
+            }
+        }
+        catch (err) {
+            this.emitter.emit("error", { error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    async *runAction(name, input) {
+        const action = this.registry.get(name);
+        if (!action) {
+            // Hallucinated action — reject silently at the model, surface to app (PRD §65).
+            yield { type: "action_result", name, ok: false, error: `Unknown action: ${name}` };
+            return;
+        }
+        if (action.isAvailable && !action.isAvailable(this.ctx.get())) {
+            yield { type: "action_result", name, ok: false, error: "Action not available in context." };
+            return;
+        }
+        const pending = {
+            name,
+            input,
+            risk: action.risk ?? "low",
+            requiresConfirmation: ActionRegistry.needsConfirmation(action),
+        };
+        this.emitter.emit("action_proposed", { name });
+        if (pending.requiresConfirmation) {
+            yield { type: "action_pending", action: pending };
+            const approved = this.confirmHandler ? await this.confirmHandler(pending) : false;
+            if (!approved) {
+                yield { type: "action_result", name, ok: false, error: "Not confirmed." };
+                return;
+            }
+            this.emitter.emit("action_confirmed", { name });
+        }
+        try {
+            const result = await action.execute(input, this.ctx.get());
+            this.emitter.emit("action_executed", { name, ok: true });
+            yield { type: "action_result", name, ok: true, result };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            this.emitter.emit("action_executed", { name, ok: false });
+            yield { type: "action_result", name, ok: false, error };
+        }
+    }
+    /** Which engine the next chat turn will use (PRD §54 privacy API). */
+    modelLocation() {
+        return this.config.model?.location();
+    }
+    on(name, handler) {
+        return this.emitter.on(name, handler);
+    }
+    async dispose() {
+        await this.config.model?.dispose();
+        this.started = false;
+    }
+    // --- internals ---
+    async loadIndex() {
+        if ("index" in this.config.knowledge && this.config.knowledge.index) {
+            const idx = this.config.knowledge.index;
+            await this.storage.putIndex(idx);
+            return idx;
+        }
+        const manifestUrl = this.config.knowledge.manifest;
+        const manifest = (await (await this.fetchFn(manifestUrl)).json());
+        const stored = await this.storage.getStoredVersion();
+        if (stored === manifest.version) {
+            const cached = await this.storage.getIndex(manifest.version);
+            if (cached)
+                return cached;
+        }
+        // Resolve the index path relative to the manifest URL.
+        const indexUrl = new URL(manifest.index, toAbsolute(manifestUrl)).toString();
+        const chunks = (await (await this.fetchFn(indexUrl)).json());
+        const index = { manifest, chunks };
+        // Compatibility guard: build-time and runtime embedders must match (PRD §25).
+        // The built-in embedder is keyed by dimensions; a real embedder should also
+        // compare manifest.embeddingModel against the runtime model id.
+        await this.storage.putIndex(index);
+        return index;
+    }
+}
+function toAbsolute(url) {
+    if (/^https?:\/\//.test(url))
+        return url;
+    const base = typeof location !== "undefined" ? location.href : "http://localhost/";
+    return new URL(url, base).toString();
+}
+function now() {
+    return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+/** Cap on an action result fed back to the model (keeps the follow-up prompt small). */
+const MAX_RESULT_CHARS = 4000;
+function truncate(s, max) {
+    return s.length > max ? `${s.slice(0, max)}… [truncated]` : s;
+}
+//# sourceMappingURL=appmind.js.map

package/dist/appmind.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Structured, app-provided description of what the user currently sees (PRD §29–31).
+ * AppMind never scrapes the DOM by default — the app pushes semantic state here.
+ */
+export interface AppMindContext {
+    route?: string;
+    page?: {
+        type?: string;
+        title?: string;
+    };
+    resource?: {
+        type?: string;
+        id?: string;
+        name?: string;
+    };
+    /** Arbitrary visible field values / form state for the current view. */
+    visibleState?: Record<string, unknown>;
+    /** Coarse global scope: org, plan, permissions, feature flags. */
+    global?: Record<string, unknown>;
+    /** Frontend permission hints — NOT authoritative (PRD §36). */
+    permissions?: string[];
+}
+/** Holds the current context and notifies listeners on change. */
+export declare class ContextStore {
+    private context;
+    private listeners;
+    get(): AppMindContext;
+    set(next: AppMindContext): void;
+    merge(patch: Partial<AppMindContext>): void;
+    subscribe(listener: (ctx: AppMindContext) => void): () => void;
+    /** Derive lightweight keyword signals from the context for retrieval biasing. */
+    keywords(): string[];
+    /** Human-readable block for the model prompt (PRD §40). */
+    toPromptBlock(): string;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,kEAAkE;AAClE,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,SAAS,CAA4C;IAE7D,GAAG,IAAI,cAAc;IAIrB,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAK/B,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;IAI3C,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI;IAK9D,iFAAiF;IACjF,QAAQ,IAAI,MAAM,EAAE;IAoBpB,2DAA2D;IAC3D,aAAa,IAAI,MAAM;CAkCxB"}

package/dist/context.js

@@ -0,0 +1,91 @@
+/** Holds the current context and notifies listeners on change. */
+export class ContextStore {
+    constructor() {
+        this.context = {};
+        this.listeners = new Set();
+    }
+    get() {
+        return this.context;
+    }
+    set(next) {
+        this.context = next;
+        for (const l of this.listeners)
+            l(next);
+    }
+    merge(patch) {
+        this.set({ ...this.context, ...patch });
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Derive lightweight keyword signals from the context for retrieval biasing. */
+    keywords() {
+        const c = this.context;
+        const words = [];
+        if (c.route)
+            words.push(...c.route.split(/[/\-_]/));
+        if (c.page?.title)
+            words.push(...c.page.title.split(/\s+/));
+        if (c.page?.type)
+            words.push(c.page.type);
+        if (c.resource?.name)
+            words.push(...c.resource.name.split(/\s+/));
+        if (c.resource?.type)
+            words.push(c.resource.type);
+        if (c.resource?.id)
+            words.push(c.resource.id);
+        for (const bag of [c.visibleState, c.global]) {
+            if (!bag)
+                continue;
+            for (const [k, v] of Object.entries(bag)) {
+                words.push(k);
+                if (typeof v === "string")
+                    words.push(v);
+            }
+        }
+        if (c.permissions)
+            words.push(...c.permissions);
+        return words.map((w) => w.toLowerCase()).filter((w) => w.length > 1);
+    }
+    /** Human-readable block for the model prompt (PRD §40). */
+    toPromptBlock() {
+        const c = this.context;
+        const lines = ["APPLICATION CONTEXT"];
+        if (c.route)
+            lines.push(`Route: ${c.route}`);
+        if (c.page?.title || c.page?.type) {
+            lines.push(`Page: ${c.page.title ?? c.page.type}`);
+        }
+        if (c.resource) {
+            // Always surface the id when there is one: actions/tools usually need it,
+            // and a display name alone leaves the model guessing (it passes the name).
+            const meta = [c.resource.type, c.resource.id && `id: ${c.resource.id}`].filter(Boolean);
+            lines.push(`Resource: ${c.resource.name ?? c.resource.id ?? ""}${meta.length ? ` (${meta.join(", ")})` : ""}`);
+        }
+        if (c.visibleState && Object.keys(c.visibleState).length > 0) {
+            lines.push("Visible state:");
+            for (const [k, v] of Object.entries(c.visibleState)) {
+                lines.push(`  ${k}: ${formatValue(v)}`);
+            }
+        }
+        if (c.global && Object.keys(c.global).length > 0) {
+            lines.push("Global:");
+            for (const [k, v] of Object.entries(c.global)) {
+                lines.push(`  ${k}: ${formatValue(v)}`);
+            }
+        }
+        if (c.permissions && c.permissions.length > 0) {
+            lines.push(`Permissions: ${c.permissions.join(", ")}`);
+        }
+        return lines.join("\n");
+    }
+}
+function formatValue(v) {
+    if (v === null || v === undefined)
+        return "—";
+    if (typeof v === "object")
+        return JSON.stringify(v);
+    return String(v);
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,41 @@
+/** Optional telemetry/lifecycle events (PRD §55). */
+export interface AppMindEvents {
+    initialized: void;
+    model_loading: {
+        provider: string;
+    };
+    model_ready: {
+        provider: string;
+        location: "local" | "remote";
+    };
+    query: {
+        text: string;
+    };
+    retrieval: {
+        count: number;
+        latencyMs: number;
+    };
+    generation: {
+        location: "local" | "remote";
+    };
+    action_proposed: {
+        name: string;
+    };
+    action_confirmed: {
+        name: string;
+    };
+    action_executed: {
+        name: string;
+        ok: boolean;
+    };
+    error: {
+        error: string;
+    };
+}
+export type EventName = keyof AppMindEvents;
+export declare class Emitter {
+    private handlers;
+    on<K extends EventName>(name: K, handler: (payload: AppMindEvents[K]) => void): () => void;
+    emit<K extends EventName>(name: K, payload: AppMindEvents[K]): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,IAAI,CAAC;IAClB,aAAa,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,WAAW,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,CAAA;KAAE,CAAC;IAChE,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACxB,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,UAAU,EAAE;QAAE,QAAQ,EAAE,OAAO,GAAG,QAAQ,CAAA;KAAE,CAAC;IAC7C,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC,gBAAgB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/C,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1B;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC;AAE5C,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAqD;IAErE,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAU1F,IAAI,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI;CAWpE"}

package/dist/events.js

@@ -0,0 +1,28 @@
+export class Emitter {
+    constructor() {
+        this.handlers = new Map();
+    }
+    on(name, handler) {
+        let set = this.handlers.get(name);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(name, set);
+        }
+        set.add(handler);
+        return () => set.delete(handler);
+    }
+    emit(name, payload) {
+        const set = this.handlers.get(name);
+        if (!set)
+            return;
+        for (const h of set) {
+            try {
+                h(payload);
+            }
+            catch {
+                /* listener errors must not break the runtime */
+            }
+        }
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAgBA,MAAM,OAAO,OAAO;IAApB;QACU,aAAQ,GAAG,IAAI,GAAG,EAA0C,CAAC;IAuBvE,CAAC;IArBC,EAAE,CAAsB,IAAO,EAAE,OAA4C;QAC3E,IAAI,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAiC,CAAC,CAAC;QAC3C,OAAO,GAAG,EAAE,CAAC,GAAI,CAAC,MAAM,CAAC,OAAiC,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,CAAsB,IAAO,EAAE,OAAyB;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;YACpB,IAAI,CAAC;gBACH,CAAC,CAAC,OAAO,CAAC,CAAC;YACb,CAAC;YAAC,MAAM,CAAC;gBACP,gDAAgD;YAClD,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { AppMind } from "./appmind.js";
+export type { AppMindConfig, ChatEvent, ChatOptions } from "./appmind.js";
+export type { AppMindContext } from "./context.js";
+export { ContextStore } from "./context.js";
+export { ActionRegistry, type AppMindAction, type ActionRisk, type PendingAction, } from "./actions.js";
+export type { AppMindModelProvider, ChatMessage, GenerationEvent, GenerationRequest, ModelLocation, ToolSpec, } from "./model.js";
+export { MemoryStorage, type AppMindStorage } from "./storage.js";
+export type { AppMindEvents, EventName } from "./events.js";
+export { buildSystemPrompt, parseToolCallFromText, estimateTokens, windowHistory, DEFAULT_PROMPT_BUDGET, type PromptBudget, type TokenCounter, } from "./runtime.js";
+export type { KnowledgeChunk, KnowledgeIndex, KnowledgeManifest, RetrievalResult, Embedder, EmbedderSpec, } from "@appmind/knowledge";
+export { createEmbedder, createDefaultEmbedder, assertEmbedderCompatible, embedText, PlaceholderEmbedder, TransformersEmbedder, PLACEHOLDER_EMBEDDER_ID, CURRENT_INDEX_SCHEMA, } from "@appmind/knowledge";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC1E,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,SAAS,EACT,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { AppMind } from "./appmind.js";
+export { ContextStore } from "./context.js";
+export { ActionRegistry, } from "./actions.js";
+export { MemoryStorage } from "./storage.js";
+export { buildSystemPrompt, parseToolCallFromText, estimateTokens, windowHistory, DEFAULT_PROMPT_BUDGET, } from "./runtime.js";
+export { createEmbedder, createDefaultEmbedder, assertEmbedderCompatible, embedText, PlaceholderEmbedder, TransformersEmbedder, PLACEHOLDER_EMBEDDER_ID, CURRENT_INDEX_SCHEMA, } from "@appmind/knowledge";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,cAAc,GAIf,MAAM,cAAc,CAAC;AAStB,OAAO,EAAE,aAAa,EAAuB,MAAM,cAAc,CAAC;AAElE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,qBAAqB,GAGtB,MAAM,cAAc,CAAC;AAWtB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,SAAS,EACT,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/model.d.ts

@@ -0,0 +1,44 @@
+/** Model provider interface (PRD §17). Implementations live in @appmind/model. */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** A tool/action description handed to the model. */
+export interface ToolSpec {
+    name: string;
+    description: string;
+    parameters?: unknown;
+}
+export interface GenerationRequest {
+    messages: ChatMessage[];
+    tools?: ToolSpec[];
+    /** Rendered application-context + knowledge block for the system prompt. */
+    system?: string;
+    signal?: AbortSignal;
+}
+export type GenerationEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "tool_call";
+    name: string;
+    arguments: unknown;
+} | {
+    type: "error";
+    error: string;
+} | {
+    type: "done";
+};
+/** Where a given generation actually ran — surfaced to the app (PRD §54). */
+export type ModelLocation = "local" | "remote";
+export interface AppMindModelProvider {
+    /** Human-readable id, e.g. "remote:anthropic" or "local:webllm". */
+    readonly id: string;
+    initialize(): Promise<void>;
+    /** Where this provider runs inference, once initialized. */
+    location(): ModelLocation;
+    supportsTools(): boolean;
+    generate(request: GenerationRequest): AsyncIterable<GenerationEvent>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/C,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,4DAA4D;IAC5D,QAAQ,IAAI,aAAa,CAAC;IAC1B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAAC,eAAe,CAAC,CAAC;IACrE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/dist/model.js

@@ -0,0 +1,3 @@
+/** Model provider interface (PRD §17). Implementations live in @appmind/model. */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,kFAAkF"}

package/dist/runtime.d.ts

@@ -0,0 +1,58 @@
+import type { RetrievalResult } from "@appmind/knowledge";
+import type { AppMindAction } from "./actions.js";
+import type { ChatMessage, ToolSpec } from "./model.js";
+/**
+ * Built-in token estimate, shaped like BPE tokenizers (cl100k/Llama-style):
+ * a common word is ~1 token and long words split every ~6 chars, digits group
+ * in threes, each punctuation/symbol is its own token, and CJK is ~1 token per
+ * character. Within ~15% of real tokenizers on prose and code — far closer
+ * than chars/4, which undercounts code and CJK badly.
+ *
+ * Still an estimate: tokenizers are model-specific and large (>1 MB), so core
+ * doesn't bundle one. For exact budgets pass `prompt.countTokens`.
+ */
+export declare function estimateTokens(text: string): number;
+/** A token counter: the built-in estimate, or a real tokenizer you supply. */
+export type TokenCounter = (text: string) => number;
+export interface PromptBudget {
+    /** Total token budget the prompt should target (default: small-model ~4K ctx). */
+    maxTokens: number;
+    /** Tokens reserved for the model's output. */
+    reservedOutputTokens: number;
+    /** Hard cap on characters kept from any single knowledge chunk. */
+    perChunkCharCap: number;
+    /** Max prior turns of conversation to keep. */
+    maxHistoryTurns: number;
+    /**
+     * Token counter used for all budgeting (default: `estimateTokens`). Plug in
+     * your model's real tokenizer for exact budgets, e.g. js-tiktoken.
+     */
+    countTokens?: TokenCounter;
+}
+export declare const DEFAULT_PROMPT_BUDGET: PromptBudget;
+/**
+ * Assemble the structured system prompt (PRD §40) within a token budget.
+ *
+ * Fill priority: system instructions → application context → top-ranked
+ * knowledge (drop lowest-ranked / truncate per chunk until it fits) → available
+ * actions. History and the user message are budgeted separately in the messages
+ * array; the caller passes the tokens those consume as `usedTokens`.
+ */
+export declare function buildSystemPrompt(contextBlock: string, knowledge: RetrievalResult[], actions: AppMindAction[], options?: {
+    budget?: Partial<PromptBudget>;
+    usedTokens?: number;
+}): string;
+export declare function toToolSpecs(actions: AppMindAction[]): ToolSpec[];
+/**
+ * Best-effort extraction of a tool call from a plain-text model response, for
+ * providers that don't emit structured tool_call events. Looks for a JSON
+ * object containing a "tool" key.
+ */
+export declare function parseToolCallFromText(text: string): {
+    name: string;
+    arguments: unknown;
+} | undefined;
+/** Keep only the last `maxTurns` messages of history (a turn = one message). */
+export declare function windowHistory(history: ChatMessage[], maxTurns: number): ChatMessage[];
+export declare function toChatMessages(history: ChatMessage[], userMessage: string, maxTurns?: number): ChatMessage[];
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUnD;AAMD,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,eAAe,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAkBF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,eAAe,EAAE,EAC5B,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACpE,MAAM,CAgDR;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,QAAQ,EAAE,CAMhE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAYlD;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAGrF;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EAAE,EACtB,WAAW,EAAE,MAAM,EACnB,QAAQ,SAAwC,GAC/C,WAAW,EAAE,CAEf"}

package/dist/runtime.js

@@ -0,0 +1,135 @@
+/**
+ * Built-in token estimate, shaped like BPE tokenizers (cl100k/Llama-style):
+ * a common word is ~1 token and long words split every ~6 chars, digits group
+ * in threes, each punctuation/symbol is its own token, and CJK is ~1 token per
+ * character. Within ~15% of real tokenizers on prose and code — far closer
+ * than chars/4, which undercounts code and CJK badly.
+ *
+ * Still an estimate: tokenizers are model-specific and large (>1 MB), so core
+ * doesn't bundle one. For exact budgets pass `prompt.countTokens`.
+ */
+export function estimateTokens(text) {
+    let tokens = 0;
+    for (const m of text.matchAll(TOKEN_PIECES)) {
+        const piece = m[0];
+        if (CJK.test(piece))
+            tokens += 1;
+        else if (/^[0-9]+$/.test(piece))
+            tokens += Math.ceil(piece.length / 3);
+        else if (WORD.test(piece))
+            tokens += 1 + Math.floor((piece.length - 1) / 6);
+        else
+            tokens += 1; // punctuation / symbol
+    }
+    return Math.max(tokens, Math.ceil(text.length / 6));
+}
+const WORD = /^[A-Za-z_\u00c0-\u024f]+$/;
+const CJK = /[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/;
+const TOKEN_PIECES = /[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]|[0-9]+|[A-Za-z_\u00c0-\u024f]+|[^\s]/g;
+export const DEFAULT_PROMPT_BUDGET = {
+    maxTokens: 4096,
+    reservedOutputTokens: 1024,
+    perChunkCharCap: 1200,
+    maxHistoryTurns: 6,
+};
+const BASE_INSTRUCTIONS = [
+    "SYSTEM INSTRUCTIONS",
+    "You are AppMind, an assistant embedded inside a web application.",
+    "Answer the user's question directly and concisely using the APPLICATION CONTEXT",
+    "and RELEVANT PRODUCT KNOWLEDGE below. If the knowledge does not cover the",
+    "question, say so briefly. Do not invent facts, and do not output JSON.",
+].join("\n");
+const TOOL_INSTRUCTIONS = [
+    "You can also perform actions, but ONLY when the user explicitly asks you to do",
+    "one of the AVAILABLE ACTIONS listed below. To perform one, reply with ONLY a",
+    'JSON object {"tool":"<name>","arguments":{...}} where <name> is exactly one of',
+    "the AVAILABLE ACTIONS — never invent an action name. For any informational or",
+    "factual question, answer in plain language and do NOT output JSON.",
+].join("\n");
+/**
+ * Assemble the structured system prompt (PRD §40) within a token budget.
+ *
+ * Fill priority: system instructions → application context → top-ranked
+ * knowledge (drop lowest-ranked / truncate per chunk until it fits) → available
+ * actions. History and the user message are budgeted separately in the messages
+ * array; the caller passes the tokens those consume as `usedTokens`.
+ */
+export function buildSystemPrompt(contextBlock, knowledge, actions, options = {}) {
+    const budget = { ...DEFAULT_PROMPT_BUDGET, ...options.budget };
+    const usedTokens = options.usedTokens ?? 0;
+    const count = budget.countTokens ?? estimateTokens;
+    // Only mention tools/JSON when actions are actually available, so the model
+    // doesn't hallucinate a tool call for a plain informational question.
+    const instructions = actions.length > 0 ? `${BASE_INSTRUCTIONS}\n\n${TOOL_INSTRUCTIONS}` : BASE_INSTRUCTIONS;
+    const parts = [instructions];
+    let spent = count(instructions) + usedTokens;
+    const ceiling = budget.maxTokens - budget.reservedOutputTokens;
+    // Application context is high priority — always included (it's small).
+    if (contextBlock.trim()) {
+        parts.push(contextBlock);
+        spent += count(contextBlock);
+    }
+    // Available actions are essential for tool calling — reserve them before knowledge.
+    const actionsBlock = actions.length > 0
+        ? `AVAILABLE ACTIONS\n${actions.map((a) => `- ${a.name}: ${a.description}`).join("\n")}`
+        : "";
+    const actionsTokens = actionsBlock ? count(actionsBlock) : 0;
+    // Fill knowledge with whatever budget remains after reserving actions.
+    const knowledgeCeiling = ceiling - actionsTokens;
+    const included = [];
+    for (let i = 0; i < knowledge.length; i++) {
+        const r = knowledge[i];
+        const content = r.content.length > budget.perChunkCharCap
+            ? r.content.slice(0, budget.perChunkCharCap) + "…"
+            : r.content;
+        const block = `[${i + 1}] ${r.title}${r.section ? ` — ${r.section}` : ""}\n${content}`;
+        const blockTokens = count(block);
+        if (spent + blockTokens > knowledgeCeiling)
+            break; // drop remaining lower-ranked chunks
+        included.push(block);
+        spent += blockTokens;
+    }
+    if (included.length > 0) {
+        parts.push(`RELEVANT PRODUCT KNOWLEDGE\n${included.join("\n\n")}`);
+    }
+    if (actionsBlock)
+        parts.push(actionsBlock);
+    return parts.join("\n\n");
+}
+export function toToolSpecs(actions) {
+    return actions.map((a) => ({
+        name: a.name,
+        description: a.description,
+        parameters: a.parameters,
+    }));
+}
+/**
+ * Best-effort extraction of a tool call from a plain-text model response, for
+ * providers that don't emit structured tool_call events. Looks for a JSON
+ * object containing a "tool" key.
+ */
+export function parseToolCallFromText(text) {
+    const match = text.match(/\{[\s\S]*"tool"[\s\S]*\}/);
+    if (!match)
+        return undefined;
+    try {
+        const parsed = JSON.parse(match[0]);
+        if (typeof parsed.tool === "string") {
+            return { name: parsed.tool, arguments: parsed.arguments ?? {} };
+        }
+    }
+    catch {
+        /* not a tool call */
+    }
+    return undefined;
+}
+/** Keep only the last `maxTurns` messages of history (a turn = one message). */
+export function windowHistory(history, maxTurns) {
+    if (history.length <= maxTurns)
+        return history;
+    return history.slice(history.length - maxTurns);
+}
+export function toChatMessages(history, userMessage, maxTurns = DEFAULT_PROMPT_BUDGET.maxHistoryTurns) {
+    return [...windowHistory(history, maxTurns), { role: "user", content: userMessage }];
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

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

package/dist/storage.d.ts

@@ -0,0 +1,27 @@
+import type { KnowledgeIndex } from "@appmind/knowledge";
+/**
+ * Persistence interface for the local knowledge index (PRD §24).
+ * MVP adapter is IndexedDB (@appmind/storage-indexeddb); an in-memory
+ * fallback ships here for SSR/Node.
+ */
+export interface AppMindStorage {
+    getIndex(version: string): Promise<KnowledgeIndex | undefined>;
+    /**
+     * Store `index` as the latest version and drop any older ones — only the
+     * current index is ever read, so keeping old versions just wastes the
+     * user's disk quota.
+     */
+    putIndex(index: KnowledgeIndex): Promise<void>;
+    getStoredVersion(): Promise<string | undefined>;
+    clear(): Promise<void>;
+}
+/** Volatile fallback — never persists. Used on the server / when no adapter is set. */
+export declare class MemoryStorage implements AppMindStorage {
+    private indexes;
+    private latest;
+    getIndex(version: string): Promise<KnowledgeIndex | undefined>;
+    putIndex(index: KnowledgeIndex): Promise<void>;
+    getStoredVersion(): Promise<string | undefined>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAChD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,uFAAuF;AACvF,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,MAAM,CAAqB;IAE7B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAG9D,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9C,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAG/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/storage.js

@@ -0,0 +1,22 @@
+/** Volatile fallback — never persists. Used on the server / when no adapter is set. */
+export class MemoryStorage {
+    constructor() {
+        this.indexes = new Map();
+    }
+    async getIndex(version) {
+        return this.indexes.get(version);
+    }
+    async putIndex(index) {
+        this.indexes.clear();
+        this.indexes.set(index.manifest.version, index);
+        this.latest = index.manifest.version;
+    }
+    async getStoredVersion() {
+        return this.latest;
+    }
+    async clear() {
+        this.indexes.clear();
+        this.latest = undefined;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAmBA,uFAAuF;AACvF,MAAM,OAAO,aAAa;IAA1B;QACU,YAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAkBtD,CAAC;IAfC,KAAK,CAAC,QAAQ,CAAC,OAAe;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IACD,KAAK,CAAC,QAAQ,CAAC,KAAqB;QAClC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;IACvC,CAAC;IACD,KAAK,CAAC,gBAAgB;QACpB,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IACD,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;CACF"}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@appmind/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "AppMind core runtime: agent orchestration, UI context, action registry, and provider interfaces.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@appmind/knowledge": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/dmitripoli/appmind#readme",
+  "bugs": {
+    "url": "https://github.com/dmitripoli/appmind/issues"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
 }