lua-cli 3.38.0 → 3.39.0

package/dist/api-exports.d.ts

@@ -3139,6 +3139,46 @@ export declare const lit: <const V extends string | number | boolean | null>(v:
 
 export { Literal }
 
+/**
+ * Structured logging: `log.debug/info/warn/error(message, fields?)`.
+ *
+ * One call writes one log row. The level becomes the row's severity, exactly as
+ * the matching `console.*` call would, and `fields` travels BESIDE the message
+ * rather than inside it — so a log drain delivers each field as its own
+ * `app.<key>` attribute that the destination can filter and group on, instead
+ * of a line someone has to parse.
+ *
+ * `console.*` is untouched: it still serialises every argument into the
+ * message text.
+ *
+ * ```typescript
+ * import { log } from 'lua-cli';
+ *
+ * log.error('Knowledge base search failed', {
+ *   tags: ['domain/search'],      // → "domain/search" + tags.count: 1
+ *   conversation_id: conversationId,
+ *   error_type: 'timeout',
+ *   duration_ms: 1432,
+ * });
+ * ```
+ *
+ * The rules, all enforced at the call so `lua test` and production agree:
+ * at most 32 keys (an array's `.count` sibling counts); a key must match
+ * `^[a-z][a-z0-9_]{0,63}$` and may not look like an API key; values are
+ * `string | number | boolean | string[]`; an array element may not contain a
+ * comma. A value over 1 KiB or a map over 8 KiB is clamped, not refused.
+ *
+ * Available in skills, tools, webhooks, triggers, jobs and processors. Workflow
+ * steps keep `ctx.log`.
+ */
+export declare const log: LuaLog;
+
+/** The `fields` argument of `log.debug/info/warn/error`. */
+export declare type LogFields = Record<string, LogFieldValue>;
+
+/** What a skill author may put in a `log.*` field map. */
+declare type LogFieldValue = string | number | boolean | string[];
+
 export declare interface LoopOptions {
     /** default 100 */
     maxIterations?: number;
@@ -3626,6 +3666,48 @@ export declare interface LuaJobConfig {
     metadata?: Record<string, any>;
 }
 
+/**
+ * The `log` global skill code sees. One call = one log row; the level is the
+ * row's `subType`, so a drain's `minSeverity` filter selects it exactly as it
+ * selects the same primitive's `console.*` lines.
+ */
+export declare interface LuaLog {
+    /** `subType: 'debug'`. */
+    debug(message: string, fields?: LogFields): void;
+    /** `subType: 'info'`. */
+    info(message: string, fields?: LogFields): void;
+    /** `subType: 'warn'`. */
+    warn(message: string, fields?: LogFields): void;
+    /** `subType: 'error'`. */
+    error(message: string, fields?: LogFields): void;
+}
+
+/**
+ * The error a `log.*` call throws when its fields are structurally invalid —
+ * too many keys, a key the pattern refuses, a nested object, a bad value type,
+ * or a comma inside an array element.
+ *
+ * Length is NOT structural: a value over 1 KiB, or a map over 8 KiB, is clamped
+ * and marked with `lua_fields_clamped: true` rather than throwing. A log call
+ * must never break a working tool.
+ *
+ * Deliberately a SHAPE, not the class: the class is not a sandbox global, and
+ * `lua compile` strips every `lua-cli` import, so an `instanceof` check written
+ * against it would type-check here and throw `ReferenceError` in the sandbox.
+ * The stable identity is `name`:
+ *
+ * ```typescript
+ * try {
+ *   log.info('searched', fields);
+ * } catch (err: any) {
+ *   if (err?.name === 'LuaLogFieldsError') await fixTheFields();
+ * }
+ * ```
+ */
+export declare type LuaLogFieldsError = Error & {
+    name: 'LuaLogFieldsError';
+};
+
 export { LuaMapConfig }
 
 /**