lua-cli 3.12.1 → 3.13.0

package/dist/utils/hints.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Post-action hint primitives (LUA-180).
+ *
+ * Pure module (no `import.meta.url`, no analytics) so it's directly testable
+ * via ts-jest. {@link ./cli.ts} re-exports these for back-compat with
+ * existing call sites.
+ *
+ * The goal: every push/deploy/chat/sync/compile/test surface ends with a
+ * one-line hint at the optimal next command — primarily `lua logs --type X`.
+ * Users (especially LLM builders running `lua chat -m "test"`) should never
+ * have to guess what to run next.
+ */
+/**
+ * Returns true when post-action hints should be silently suppressed.
+ * Honors the `LUA_NO_HINTS` env var (any truthy value disables hints).
+ *
+ * Used by both {@link writeTip}/{@link writeNextStep} and the
+ * `withErrorHandling` `onError` hook so users can opt out of all hint noise
+ * with a single env var.
+ */
+export declare function hintsDisabled(): boolean;
+/**
+ * Render a free-form tip line. Format: `✨ Tip: <message>`.
+ *
+ * Honors {@link hintsDisabled} (LUA_NO_HINTS=1 silently no-ops). For tips
+ * that point at a specific follow-up command, prefer {@link writeNextStep}
+ * which renders the command in backticks with a consistent verb.
+ */
+export declare function writeTip(message: string): void;
+/**
+ * Options for {@link writeNextStep}.
+ */
+export interface NextStepOptions {
+    /**
+     * The follow-up command to surface, e.g. `"lua logs --type skill --limit 10"`.
+     * Rendered in backticks.
+     */
+    command: string;
+    /**
+     * Optional rationale appended after the command. A trailing period is added
+     * automatically if missing, e.g.
+     *   rationale: "to inspect runtime behavior"
+     *   → `✨ Tip: run \`<cmd>\` to inspect runtime behavior.`
+     */
+    rationale?: string;
+    /**
+     * Controls icon and label.
+     *   - `success` (default) → `✨ Tip: run \`<cmd>\` ...`
+     *   - `error`             → `💡 Diagnose: run \`<cmd>\` ...`
+     *   - `partial`           → `⚠️  Diagnose: run \`<cmd>\` ...`
+     */
+    when?: 'success' | 'error' | 'partial';
+}
+/**
+ * Render a "what to do next" hint pointing at a specific CLI command.
+ * Used after every push/deploy/chat/sync/compile/test action to make
+ * the optimal next command obvious to users and AI builders.
+ *
+ * Honors {@link hintsDisabled} (LUA_NO_HINTS=1 silently no-ops).
+ */
+export declare function writeNextStep(opts: NextStepOptions): void;
+export interface HintBlockLine {
+    label: string;
+    command: string;
+}
+/**
+ * Render a multi-line contextual hint block.
+ * Used when the optimal next action involves a sequence of commands or
+ * when a single-line hint would be too narrow (e.g., deploy-then-test).
+ *
+ * Output format:
+ *   ✨ <headline>
+ *      <label>  <command>
+ *      <label>  <command>
+ */
+export declare function writeHintBlock(opts: {
+    headline: string;
+    lines: HintBlockLine[];
+    when?: 'success' | 'error' | 'partial';
+}): void;
+//# sourceMappingURL=hints.d.ts.map

package/dist/utils/hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hints.d.ts","sourceRoot":"","sources":["../../src/utils/hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAGvC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG9C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;CACxC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAUzD;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;CACxC,GAAG,IAAI,CAcP"}

package/dist/utils/hints.js

@@ -0,0 +1,83 @@
+/**
+ * Post-action hint primitives (LUA-180).
+ *
+ * Pure module (no `import.meta.url`, no analytics) so it's directly testable
+ * via ts-jest. {@link ./cli.ts} re-exports these for back-compat with
+ * existing call sites.
+ *
+ * The goal: every push/deploy/chat/sync/compile/test surface ends with a
+ * one-line hint at the optimal next command — primarily `lua logs --type X`.
+ * Users (especially LLM builders running `lua chat -m "test"`) should never
+ * have to guess what to run next.
+ */
+import { writeInfo } from './write-info.js';
+/**
+ * Returns true when post-action hints should be silently suppressed.
+ * Honors the `LUA_NO_HINTS` env var (any truthy value disables hints).
+ *
+ * Used by both {@link writeTip}/{@link writeNextStep} and the
+ * `withErrorHandling` `onError` hook so users can opt out of all hint noise
+ * with a single env var.
+ */
+export function hintsDisabled() {
+    const v = process.env.LUA_NO_HINTS;
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/**
+ * Render a free-form tip line. Format: `✨ Tip: <message>`.
+ *
+ * Honors {@link hintsDisabled} (LUA_NO_HINTS=1 silently no-ops). For tips
+ * that point at a specific follow-up command, prefer {@link writeNextStep}
+ * which renders the command in backticks with a consistent verb.
+ */
+export function writeTip(message) {
+    if (hintsDisabled())
+        return;
+    writeInfo(`✨ Tip: ${message}`);
+}
+/**
+ * Render a "what to do next" hint pointing at a specific CLI command.
+ * Used after every push/deploy/chat/sync/compile/test action to make
+ * the optimal next command obvious to users and AI builders.
+ *
+ * Honors {@link hintsDisabled} (LUA_NO_HINTS=1 silently no-ops).
+ */
+export function writeNextStep(opts) {
+    if (hintsDisabled())
+        return;
+    const when = opts.when ?? 'success';
+    const icon = when === 'error' ? '💡' : when === 'partial' ? '⚠️ ' : '✨';
+    const label = when === 'success' ? 'Tip' : 'Diagnose';
+    const rationale = opts.rationale?.trim();
+    const tail = rationale
+        ? ` ${rationale}${/[.!?]$/.test(rationale) ? '' : '.'}`
+        : '';
+    writeInfo(`${icon} ${label}: run \`${opts.command}\`${tail}`);
+}
+/**
+ * Render a multi-line contextual hint block.
+ * Used when the optimal next action involves a sequence of commands or
+ * when a single-line hint would be too narrow (e.g., deploy-then-test).
+ *
+ * Output format:
+ *   ✨ <headline>
+ *      <label>  <command>
+ *      <label>  <command>
+ */
+export function writeHintBlock(opts) {
+    if (hintsDisabled())
+        return;
+    const validLines = opts.lines.filter(l => l.command && l.command.trim().length > 0);
+    const when = opts.when ?? 'success';
+    const icon = when === 'error' ? '💡' : when === 'partial' ? '⚠️ ' : '✨';
+    if (validLines.length === 0) {
+        writeInfo(`${icon} ${opts.headline}`);
+        return;
+    }
+    writeInfo(`${icon} ${opts.headline}`);
+    const maxLabelLen = Math.max(...validLines.map(l => l.label.length));
+    for (const { label, command } of validLines) {
+        writeInfo(`   ${label.padEnd(maxLabelLen)}  \`${command}\``);
+    }
+}
+//# sourceMappingURL=hints.js.map

package/dist/utils/hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hints.js","sourceRoot":"","sources":["../../src/utils/hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACnC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,KAAK,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,IAAI,aAAa,EAAE;QAAE,OAAO;IAC5B,SAAS,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;AACjC,CAAC;AA2BD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAqB;IACjD,IAAI,aAAa,EAAE;QAAE,OAAO;IAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;IACxE,MAAM,KAAK,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,SAAS;QACpB,CAAC,CAAC,IAAI,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE;QACvD,CAAC,CAAC,EAAE,CAAC;IACP,SAAS,CAAC,GAAG,IAAI,IAAI,KAAK,WAAW,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC,CAAC;AAChE,CAAC;AAOD;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAI9B;IACC,IAAI,aAAa,EAAE;QAAE,OAAO;IAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;IACxE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,SAAS,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACtC,OAAO;IACT,CAAC;IACD,SAAS,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IACtC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACrE,KAAK,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5C,SAAS,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,OAAO,IAAI,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC"}

package/dist/utils/suggest.d.ts

@@ -0,0 +1,3 @@
+export declare function levenshtein(a: string, b: string): number;
+export declare function suggestClosest(input: string, candidates: string[]): string | null;
+//# sourceMappingURL=suggest.d.ts.map

package/dist/utils/suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../src/utils/suggest.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAaxD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAcjF"}

package/dist/utils/suggest.js

@@ -0,0 +1,34 @@
+export function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+export function suggestClosest(input, candidates) {
+    const lower = input.toLowerCase();
+    let best = null;
+    let bestDist = Infinity;
+    for (const c of candidates) {
+        const dist = levenshtein(lower, c.toLowerCase());
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = c;
+        }
+    }
+    if (!best || bestDist > 6)
+        return null;
+    if (bestDist >= (lower.length + best.length + 1) * 0.4)
+        return null;
+    return best;
+}
+//# sourceMappingURL=suggest.js.map

package/dist/utils/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../../src/utils/suggest.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,MAAM,EAAE,GAAe,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;QAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;QAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC9B,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAClB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,UAAoB;IAChE,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAClC,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,QAAQ,GAAG,QAAQ,CAAC;IACxB,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QACjD,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;YACpB,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,GAAG,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IACD,IAAI,CAAC,IAAI,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,QAAQ,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IACpE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/write-info.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pure stdout writer (extracted so {@link ./hints.ts} stays importable in
+ * tests — `cli.ts` itself uses `import.meta.url` which ts-jest can't compile).
+ *
+ * Mirrors the existing `writeInfo` from `./cli.ts`: clears the current
+ * progress line via `\r\x1b[K` and writes `<message>\n`.
+ */
+export declare function writeInfo(message: string): void;
+//# sourceMappingURL=write-info.d.ts.map

package/dist/utils/write-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-info.d.ts","sourceRoot":"","sources":["../../src/utils/write-info.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C"}

package/dist/utils/write-info.js

@@ -0,0 +1,11 @@
+/**
+ * Pure stdout writer (extracted so {@link ./hints.ts} stays importable in
+ * tests — `cli.ts` itself uses `import.meta.url` which ts-jest can't compile).
+ *
+ * Mirrors the existing `writeInfo` from `./cli.ts`: clears the current
+ * progress line via `\r\x1b[K` and writes `<message>\n`.
+ */
+export function writeInfo(message) {
+    process.stdout.write('\r\x1b[K' + message + '\n');
+}
+//# sourceMappingURL=write-info.js.map

package/dist/utils/write-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-info.js","sourceRoot":"","sources":["../../src/utils/write-info.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;AACpD,CAAC"}

package/docs/README.md

@@ -1,6 +1,6 @@
 # Lua CLI - Complete API Documentation
 
-Welcome to the comprehensive API documentation for lua-cli v3.12.0. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.13.0. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 

package/node_modules/@lua/shared-types/dist/index.d.mts

@@ -5,7 +5,7 @@ import { FinishReason, LanguageModelUsage, ReasoningOutput, CallWarning, UserCon
  * Represents the communication channel through which a request originated.
  * Known channels are typed as string literals, unrecognized channels are unknown.
  */
-type Channel = 'web' | 'whatsapp' | 'facebook' | 'instagram' | 'slack' | 'teams' | 'messagebird' | 'front' | 'api' | 'dev' | 'email' | 'rcs' | 'sms' | 'mms' | 'device' | string;
+type Channel = 'web' | 'meeting' | 'whatsapp' | 'facebook' | 'instagram' | 'slack' | 'teams' | 'messagebird' | 'front' | 'api' | 'dev' | 'email' | 'rcs' | 'sms' | 'mms' | 'device' | string;
 
 /**
  * MIME types supported by Unstructured.io for document text extraction.
@@ -337,6 +337,50 @@ interface CachedDeviceTriggerDefinition {
     env: Record<string, string>;
 }
 
+/**
+ * Client-Injected Tools
+ *
+ * Lets a chat client (Lua Desktop, custom front-ends, future surfaces) declare
+ * tools that the agent can call but the *client* renders/handles. Mirrors the
+ * pattern used by Claude Code, OpenAI Apps SDK, and Anthropic's MCP — the
+ * surface the user sees gets to add capabilities to the agent without changing
+ * the agent itself.
+ *
+ * Tool calls flow through Mastra's existing `tool-call` stream chunks; the
+ * server registers the tool with a no-op `execute` (returns `{ ok: true,
+ * clientHandled: true }`) so the model sees a clean ack and can continue. The
+ * actual rendering / side-effect happens on the client when it sees the
+ * tool-call chunk.
+ *
+ * Tool names are namespaced server-side as `client__<name>` to avoid collisions
+ * with built-in tools (skills, MCP, devices, voice). Same pattern as device
+ * tools (`device__<name>__<command>`).
+ */
+interface ClientToolDef {
+    /** Unprefixed tool name as the client refers to it (e.g. "create_artifact"). Server prefixes with `client__`. */
+    name: string;
+    /** Human/LLM-readable description of when to call this tool. */
+    description: string;
+    /**
+     * JSON Schema for the tool's input. Hydrated server-side into a Zod schema
+     * via the shared `jsonSchemaToZod` util. Same subset supported as device
+     * tools — object with string/number/boolean/array properties, `required`,
+     * `default`, `description`, `enum`.
+     */
+    parameters: Record<string, unknown>;
+}
+/**
+ * Server-side prefix for client tool names. Keeps client tools from
+ * shadowing skills, MCP tools, devices (`device__`), or voice tools.
+ */
+declare const CLIENT_TOOL_PREFIX = "client__";
+/**
+ * Maximum number of client tools accepted per request. Keeps the model's
+ * tool list bounded — at this many tools the model starts losing precision
+ * picking the right one anyway.
+ */
+declare const CLIENT_TOOLS_MAX = 20;
+
 /**
  * Shared type definitions for the model registry.
  *
@@ -396,4 +440,22 @@ interface GovernanceConfig {
  */
 declare function buildDefaultPersona(agentName: string): string;
 
-export { type AgentInvocationInput, type AgentInvocationOutput, type AiGenerateInput, type AiGenerateOutput, type AiGenerateSource, type AiGenerateToolCall, type AiGenerateToolResult, type ApprovedModelDef, type BatchingConfig, type CachedDeviceCommand, type CachedDeviceDefinition, type CachedDeviceTrigger, type CachedDeviceTriggerDefinition, type Channel, type CommandHashData, type CommandState, type CommandStreamEntry, type DeviceCommandDefinition, type DeviceCommandMessage, type DeviceInfo, type DeviceResponseMessage, type DeviceStatus, type DeviceTriggerAckMessage, type DeviceTriggerMessage, type GovernanceConfig, REQUIRED_ENUMS, REQUIRED_NESTED_APIS, REQUIRED_PLATFORM_APIS, REQUIRED_PRIMITIVE_SHIMS, REQUIRED_UTILITIES, type ResponseStreamEntry, type TriggerStreamEntry, UNSTRUCTURED_SUPPORTED_MEDIA_TYPES, aiGenerateInputFromSimplified, buildDefaultPersona };
+declare const AGENT_LOG_SOURCES: readonly ["skill", "job", "webhook", "preprocessor", "postprocessor", "user_message", "agent_response", "agent_error", "runtime", "mcp", "rag", "device", "device-trigger"];
+type AgentLogSource = (typeof AGENT_LOG_SOURCES)[number];
+interface AgentLogMetadata {
+    userId?: string;
+    agentId?: string;
+    /** Agent runtime / conversation thread ID for distributed tracing */
+    runId?: string;
+    logSource?: AgentLogSource;
+    /** The ID of the source entity (skillId, jobId, webhookId, etc.) */
+    primitiveId?: string;
+    /** The display name of the source entity */
+    primitiveName?: string;
+    toolId?: string;
+    toolName?: string;
+    /** Messaging channel: 'whatsapp', 'slack', 'email', etc. */
+    channel?: string;
+}
+
+export { AGENT_LOG_SOURCES, type AgentInvocationInput, type AgentInvocationOutput, type AgentLogMetadata, type AgentLogSource, type AiGenerateInput, type AiGenerateOutput, type AiGenerateSource, type AiGenerateToolCall, type AiGenerateToolResult, type ApprovedModelDef, type BatchingConfig, CLIENT_TOOLS_MAX, CLIENT_TOOL_PREFIX, type CachedDeviceCommand, type CachedDeviceDefinition, type CachedDeviceTrigger, type CachedDeviceTriggerDefinition, type Channel, type ClientToolDef, type CommandHashData, type CommandState, type CommandStreamEntry, type DeviceCommandDefinition, type DeviceCommandMessage, type DeviceInfo, type DeviceResponseMessage, type DeviceStatus, type DeviceTriggerAckMessage, type DeviceTriggerMessage, type GovernanceConfig, REQUIRED_ENUMS, REQUIRED_NESTED_APIS, REQUIRED_PLATFORM_APIS, REQUIRED_PRIMITIVE_SHIMS, REQUIRED_UTILITIES, type ResponseStreamEntry, type TriggerStreamEntry, UNSTRUCTURED_SUPPORTED_MEDIA_TYPES, aiGenerateInputFromSimplified, buildDefaultPersona };

package/node_modules/@lua/shared-types/dist/index.d.ts

@@ -5,7 +5,7 @@ import { FinishReason, LanguageModelUsage, ReasoningOutput, CallWarning, UserCon
  * Represents the communication channel through which a request originated.
  * Known channels are typed as string literals, unrecognized channels are unknown.
  */
-type Channel = 'web' | 'whatsapp' | 'facebook' | 'instagram' | 'slack' | 'teams' | 'messagebird' | 'front' | 'api' | 'dev' | 'email' | 'rcs' | 'sms' | 'mms' | 'device' | string;
+type Channel = 'web' | 'meeting' | 'whatsapp' | 'facebook' | 'instagram' | 'slack' | 'teams' | 'messagebird' | 'front' | 'api' | 'dev' | 'email' | 'rcs' | 'sms' | 'mms' | 'device' | string;
 
 /**
  * MIME types supported by Unstructured.io for document text extraction.
@@ -337,6 +337,50 @@ interface CachedDeviceTriggerDefinition {
     env: Record<string, string>;
 }
 
+/**
+ * Client-Injected Tools
+ *
+ * Lets a chat client (Lua Desktop, custom front-ends, future surfaces) declare
+ * tools that the agent can call but the *client* renders/handles. Mirrors the
+ * pattern used by Claude Code, OpenAI Apps SDK, and Anthropic's MCP — the
+ * surface the user sees gets to add capabilities to the agent without changing
+ * the agent itself.
+ *
+ * Tool calls flow through Mastra's existing `tool-call` stream chunks; the
+ * server registers the tool with a no-op `execute` (returns `{ ok: true,
+ * clientHandled: true }`) so the model sees a clean ack and can continue. The
+ * actual rendering / side-effect happens on the client when it sees the
+ * tool-call chunk.
+ *
+ * Tool names are namespaced server-side as `client__<name>` to avoid collisions
+ * with built-in tools (skills, MCP, devices, voice). Same pattern as device
+ * tools (`device__<name>__<command>`).
+ */
+interface ClientToolDef {
+    /** Unprefixed tool name as the client refers to it (e.g. "create_artifact"). Server prefixes with `client__`. */
+    name: string;
+    /** Human/LLM-readable description of when to call this tool. */
+    description: string;
+    /**
+     * JSON Schema for the tool's input. Hydrated server-side into a Zod schema
+     * via the shared `jsonSchemaToZod` util. Same subset supported as device
+     * tools — object with string/number/boolean/array properties, `required`,
+     * `default`, `description`, `enum`.
+     */
+    parameters: Record<string, unknown>;
+}
+/**
+ * Server-side prefix for client tool names. Keeps client tools from
+ * shadowing skills, MCP tools, devices (`device__`), or voice tools.
+ */
+declare const CLIENT_TOOL_PREFIX = "client__";
+/**
+ * Maximum number of client tools accepted per request. Keeps the model's
+ * tool list bounded — at this many tools the model starts losing precision
+ * picking the right one anyway.
+ */
+declare const CLIENT_TOOLS_MAX = 20;
+
 /**
  * Shared type definitions for the model registry.
  *
@@ -396,4 +440,22 @@ interface GovernanceConfig {
  */
 declare function buildDefaultPersona(agentName: string): string;
 
-export { type AgentInvocationInput, type AgentInvocationOutput, type AiGenerateInput, type AiGenerateOutput, type AiGenerateSource, type AiGenerateToolCall, type AiGenerateToolResult, type ApprovedModelDef, type BatchingConfig, type CachedDeviceCommand, type CachedDeviceDefinition, type CachedDeviceTrigger, type CachedDeviceTriggerDefinition, type Channel, type CommandHashData, type CommandState, type CommandStreamEntry, type DeviceCommandDefinition, type DeviceCommandMessage, type DeviceInfo, type DeviceResponseMessage, type DeviceStatus, type DeviceTriggerAckMessage, type DeviceTriggerMessage, type GovernanceConfig, REQUIRED_ENUMS, REQUIRED_NESTED_APIS, REQUIRED_PLATFORM_APIS, REQUIRED_PRIMITIVE_SHIMS, REQUIRED_UTILITIES, type ResponseStreamEntry, type TriggerStreamEntry, UNSTRUCTURED_SUPPORTED_MEDIA_TYPES, aiGenerateInputFromSimplified, buildDefaultPersona };
+declare const AGENT_LOG_SOURCES: readonly ["skill", "job", "webhook", "preprocessor", "postprocessor", "user_message", "agent_response", "agent_error", "runtime", "mcp", "rag", "device", "device-trigger"];
+type AgentLogSource = (typeof AGENT_LOG_SOURCES)[number];
+interface AgentLogMetadata {
+    userId?: string;
+    agentId?: string;
+    /** Agent runtime / conversation thread ID for distributed tracing */
+    runId?: string;
+    logSource?: AgentLogSource;
+    /** The ID of the source entity (skillId, jobId, webhookId, etc.) */
+    primitiveId?: string;
+    /** The display name of the source entity */
+    primitiveName?: string;
+    toolId?: string;
+    toolName?: string;
+    /** Messaging channel: 'whatsapp', 'slack', 'email', etc. */
+    channel?: string;
+}
+
+export { AGENT_LOG_SOURCES, type AgentInvocationInput, type AgentInvocationOutput, type AgentLogMetadata, type AgentLogSource, type AiGenerateInput, type AiGenerateOutput, type AiGenerateSource, type AiGenerateToolCall, type AiGenerateToolResult, type ApprovedModelDef, type BatchingConfig, CLIENT_TOOLS_MAX, CLIENT_TOOL_PREFIX, type CachedDeviceCommand, type CachedDeviceDefinition, type CachedDeviceTrigger, type CachedDeviceTriggerDefinition, type Channel, type ClientToolDef, type CommandHashData, type CommandState, type CommandStreamEntry, type DeviceCommandDefinition, type DeviceCommandMessage, type DeviceInfo, type DeviceResponseMessage, type DeviceStatus, type DeviceTriggerAckMessage, type DeviceTriggerMessage, type GovernanceConfig, REQUIRED_ENUMS, REQUIRED_NESTED_APIS, REQUIRED_PLATFORM_APIS, REQUIRED_PRIMITIVE_SHIMS, REQUIRED_UTILITIES, type ResponseStreamEntry, type TriggerStreamEntry, UNSTRUCTURED_SUPPORTED_MEDIA_TYPES, aiGenerateInputFromSimplified, buildDefaultPersona };

package/node_modules/@lua/shared-types/dist/index.js

@@ -20,6 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AGENT_LOG_SOURCES: () => AGENT_LOG_SOURCES,
+  CLIENT_TOOLS_MAX: () => CLIENT_TOOLS_MAX,
+  CLIENT_TOOL_PREFIX: () => CLIENT_TOOL_PREFIX,
   REQUIRED_ENUMS: () => REQUIRED_ENUMS,
   REQUIRED_NESTED_APIS: () => REQUIRED_NESTED_APIS,
   REQUIRED_PLATFORM_APIS: () => REQUIRED_PLATFORM_APIS,
@@ -208,6 +211,10 @@ var REQUIRED_UTILITIES = [
   "env"
 ];
 
+// src/client-tools.types.ts
+var CLIENT_TOOL_PREFIX = "client__";
+var CLIENT_TOOLS_MAX = 20;
+
 // src/persona-defaults.ts
 var AGENT_NAME_TOKEN = "[Your Agent Name]";
 var DEFAULT_PERSONA_GUIDE = `# ${AGENT_NAME_TOKEN} - Persona
@@ -260,8 +267,28 @@ function buildDefaultPersona(agentName) {
   return DEFAULT_PERSONA_GUIDE.replace(AGENT_NAME_TOKEN, () => agentName || "My Agent");
 }
 __name(buildDefaultPersona, "buildDefaultPersona");
+
+// src/vm-execution-log.types.ts
+var AGENT_LOG_SOURCES = [
+  "skill",
+  "job",
+  "webhook",
+  "preprocessor",
+  "postprocessor",
+  "user_message",
+  "agent_response",
+  "agent_error",
+  "runtime",
+  "mcp",
+  "rag",
+  "device",
+  "device-trigger"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AGENT_LOG_SOURCES,
+  CLIENT_TOOLS_MAX,
+  CLIENT_TOOL_PREFIX,
   REQUIRED_ENUMS,
   REQUIRED_NESTED_APIS,
   REQUIRED_PLATFORM_APIS,

package/node_modules/@lua/shared-types/dist/index.mjs

@@ -178,6 +178,10 @@ var REQUIRED_UTILITIES = [
   "env"
 ];
 
+// src/client-tools.types.ts
+var CLIENT_TOOL_PREFIX = "client__";
+var CLIENT_TOOLS_MAX = 20;
+
 // src/persona-defaults.ts
 var AGENT_NAME_TOKEN = "[Your Agent Name]";
 var DEFAULT_PERSONA_GUIDE = `# ${AGENT_NAME_TOKEN} - Persona
@@ -230,7 +234,27 @@ function buildDefaultPersona(agentName) {
   return DEFAULT_PERSONA_GUIDE.replace(AGENT_NAME_TOKEN, () => agentName || "My Agent");
 }
 __name(buildDefaultPersona, "buildDefaultPersona");
+
+// src/vm-execution-log.types.ts
+var AGENT_LOG_SOURCES = [
+  "skill",
+  "job",
+  "webhook",
+  "preprocessor",
+  "postprocessor",
+  "user_message",
+  "agent_response",
+  "agent_error",
+  "runtime",
+  "mcp",
+  "rag",
+  "device",
+  "device-trigger"
+];
 export {
+  AGENT_LOG_SOURCES,
+  CLIENT_TOOLS_MAX,
+  CLIENT_TOOL_PREFIX,
   REQUIRED_ENUMS,
   REQUIRED_NESTED_APIS,
   REQUIRED_PLATFORM_APIS,

package/node_modules/@lua/shared-types/src/channel.type.ts

@@ -5,6 +5,7 @@
  */
 export type Channel =
   | 'web' // Chat widget on a website
+  | 'meeting' // Recall.ai-backed meeting transport
   | 'whatsapp' // WhatsApp integration
   | 'facebook' // Facebook Messenger integration
   | 'instagram' // Instagram integration

package/node_modules/@lua/shared-types/src/client-tools.types.ts

@@ -0,0 +1,47 @@
+/**
+ * Client-Injected Tools
+ *
+ * Lets a chat client (Lua Desktop, custom front-ends, future surfaces) declare
+ * tools that the agent can call but the *client* renders/handles. Mirrors the
+ * pattern used by Claude Code, OpenAI Apps SDK, and Anthropic's MCP — the
+ * surface the user sees gets to add capabilities to the agent without changing
+ * the agent itself.
+ *
+ * Tool calls flow through Mastra's existing `tool-call` stream chunks; the
+ * server registers the tool with a no-op `execute` (returns `{ ok: true,
+ * clientHandled: true }`) so the model sees a clean ack and can continue. The
+ * actual rendering / side-effect happens on the client when it sees the
+ * tool-call chunk.
+ *
+ * Tool names are namespaced server-side as `client__<name>` to avoid collisions
+ * with built-in tools (skills, MCP, devices, voice). Same pattern as device
+ * tools (`device__<name>__<command>`).
+ */
+export interface ClientToolDef {
+  /** Unprefixed tool name as the client refers to it (e.g. "create_artifact"). Server prefixes with `client__`. */
+  name: string;
+
+  /** Human/LLM-readable description of when to call this tool. */
+  description: string;
+
+  /**
+   * JSON Schema for the tool's input. Hydrated server-side into a Zod schema
+   * via the shared `jsonSchemaToZod` util. Same subset supported as device
+   * tools — object with string/number/boolean/array properties, `required`,
+   * `default`, `description`, `enum`.
+   */
+  parameters: Record<string, unknown>;
+}
+
+/**
+ * Server-side prefix for client tool names. Keeps client tools from
+ * shadowing skills, MCP tools, devices (`device__`), or voice tools.
+ */
+export const CLIENT_TOOL_PREFIX = 'client__';
+
+/**
+ * Maximum number of client tools accepted per request. Keeps the model's
+ * tool list bounded — at this many tools the model starts losing precision
+ * picking the right one anyway.
+ */
+export const CLIENT_TOOLS_MAX = 20;

package/node_modules/@lua/shared-types/src/index.ts

@@ -5,6 +5,8 @@ export * from './ai-generate.utils';
 export * from './agent-invocation.types';
 export * from './sandbox-contract';
 export * from './device.types';
+export * from './client-tools.types';
 export * from './model-registry';
 export * from './agent-config.types';
 export * from './persona-defaults';
+export * from './vm-execution-log.types';

package/node_modules/@lua/shared-types/src/vm-execution-log.types.ts

@@ -0,0 +1,41 @@
+// ─── Canonical log-source enum ────────────────────────────────────────────────
+// Single source of truth for all `logSource` values written to the
+// `vmExecutionLogs` collection. Every consumer (lua-core, lua-api, lua-cli,
+// lua-web) must import from here — never define the union inline elsewhere.
+//
+// NOTE: This lives in shared-types (not shared-schemas) so that lightweight
+// consumers such as lua-cli can import it without pulling in Mongoose schemas.
+
+export const AGENT_LOG_SOURCES = [
+  'skill',          // User-defined skill executions
+  'job',            // Scheduled job executions
+  'webhook',        // HTTP webhook endpoint executions
+  'preprocessor',   // Message preprocessor executions
+  'postprocessor',  // Response postprocessor executions
+  'user_message',   // Incoming user messages
+  'agent_response', // Outgoing agent responses
+  'agent_error',    // Chat pipeline errors (billing, validation, LLM failures)
+  'runtime',        // Agent runtime / LLM SDK / MCP transport / framework-level logs
+  'mcp',            // MCP tool executions
+  'rag',            // RAG knowledge-base search executions
+  'device',         // Device command executions
+  'device-trigger', // Device trigger handler executions
+] as const;
+
+export type AgentLogSource = (typeof AGENT_LOG_SOURCES)[number];
+
+export interface AgentLogMetadata {
+  userId?: string;
+  agentId?: string;
+  /** Agent runtime / conversation thread ID for distributed tracing */
+  runId?: string;
+  logSource?: AgentLogSource;
+  /** The ID of the source entity (skillId, jobId, webhookId, etc.) */
+  primitiveId?: string;
+  /** The display name of the source entity */
+  primitiveName?: string;
+  toolId?: string;
+  toolName?: string;
+  /** Messaging channel: 'whatsapp', 'slack', 'email', etc. */
+  channel?: string;
+}