@skrr-ai/cli 0.1.102 → 0.1.103

package/dist/lib/triggers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.triggerApi = exports.AgentTriggerScopeError = exports.SCOPE_IMPLIED_REF_KEY = exports.TRIGGER_EVENT_CATALOG = exports.TRIGGER_EVENT_ENTITY_TYPES = exports.TRIGGER_CHAT_AUTH_MODES = exports.TRIGGER_CHAT_RESPONSE_MODES = exports.TRIGGER_CHAT_MODES = exports.TRIGGER_FORM_RESPONSE_MODES = exports.TRIGGER_CONCURRENCY_POLICIES = exports.TRIGGER_EVENT_FILTER_MODES = exports.TRIGGER_EXECUTOR_MODES = exports.TRIGGER_SCOPE_KINDS = exports.TRIGGER_KINDS = void 0;
+exports.triggerApi = exports.AgentTriggerScopeError = exports.FLAG_OWNER_KINDS = exports.SCOPE_IMPLIED_REF_KEY = exports.TRIGGER_EVENT_CATALOG = exports.TRIGGER_EVENT_ENTITY_TYPES = exports.TRIGGER_CHAT_AUTH_MODES = exports.TRIGGER_CHAT_RESPONSE_MODES = exports.TRIGGER_CHAT_MODES = exports.TRIGGER_FORM_RESPONSE_MODES = exports.TRIGGER_CONCURRENCY_POLICIES = exports.TRIGGER_EVENT_FILTER_MODES = exports.TRIGGER_EXECUTOR_MODES = exports.TRIGGER_SCOPE_KINDS = exports.TRIGGER_KINDS = void 0;
 exports.validateEventReference = validateEventReference;
 exports.validateEventFilter = validateEventFilter;
 exports.serverEventCatalogIncludes = serverEventCatalogIncludes;
@@ -13,6 +13,8 @@ exports.buildScheduleConfigFromFlags = buildScheduleConfigFromFlags;
 exports.assertScheduleTimingShape = assertScheduleTimingShape;
 exports.buildOnceConfigFromFlags = buildOnceConfigFromFlags;
 exports.buildSelfScheduledConfigFromFlags = buildSelfScheduledConfigFromFlags;
+exports.buildEventConfigFromFlags = buildEventConfigFromFlags;
+exports.buildStochasticConfigFromFlags = buildStochasticConfigFromFlags;
 exports.buildFormConfigFromFlags = buildFormConfigFromFlags;
 exports.buildChatMessageConfigFromFlags = buildChatMessageConfigFromFlags;
 exports.parseExecutionReferences = parseExecutionReferences;
@@ -21,6 +23,8 @@ exports.assertEmbeddedActionTokensBound = assertEmbeddedActionTokensBound;
 exports.setDefined = setDefined;
 exports.mergeObjectField = mergeObjectField;
 exports.mergeTriggerKindConfig = mergeTriggerKindConfig;
+exports.assertKindFlagsApply = assertKindFlagsApply;
+exports.describeScheduledFire = describeScheduledFire;
 exports.withQuery = withQuery;
 exports.agentScope = agentScope;
 exports.spaceSubscriberScope = spaceSubscriberScope;
@@ -461,6 +465,29 @@ function buildSelfScheduledConfigFromFlags(flags) {
     });
     return selfScheduled;
 }
+function buildEventConfigFromFlags(flags, filterValues) {
+    const event = {};
+    setDefined(event, {
+        entityType: flags.entity,
+        eventType: flags.event,
+        filterMode: flags['filter-mode'],
+        filterField: flags['filter-field'],
+        filterValue: filterValues && filterValues.length > 1 ? filterValues : filterValues?.[0],
+        debounceMs: flags['debounce-ms'],
+        maxPerHour: flags['max-per-hour'],
+    });
+    return event;
+}
+function buildStochasticConfigFromFlags(flags) {
+    const stochastic = {};
+    setDefined(stochastic, {
+        probability: flags.probability === undefined ? undefined : Number(flags.probability),
+        jitterMs: flags['jitter-ms'],
+        maxFiresPerDay: flags['max-fires-per-day'],
+        evalIntervalMinutes: flags['eval-interval-minutes'],
+    });
+    return stochastic;
+}
 function buildFormConfigFromFlags(flags) {
     const form = {};
     const fields = parseJsonArray(flags['form-fields'], '--form-fields');
@@ -633,6 +660,112 @@ function mergeTriggerKindConfig(target, kind, configs) {
         return;
     mergeObjectField(target, key, configs[key]);
 }
+/**
+ * The kinds whose config block each kind-specific flag fills. A flag that is not listed
+ * (--label, --mode, --prompt, --concurrency-key …) belongs to every kind.
+ *
+ * `mergeTriggerKindConfig` keeps only the block the chosen kind owns, so a flag for another
+ * kind used to be accepted and thrown away: `--max-fires-per-day 1` on an on_demand trigger
+ * stored no cap, `preflight` said `no_cap`, and the second fire still ran (OSK-15491).
+ * Declared beside the builders above, which are what read these flags.
+ */
+exports.FLAG_OWNER_KINDS = Object.freeze({
+    cron: ['schedule'],
+    'interval-ms': ['schedule'],
+    'interval-minutes': ['schedule'],
+    'daily-time': ['schedule'],
+    'max-runs': ['schedule'],
+    'end-at': ['schedule'],
+    'stale-catchup-ms': ['schedule'],
+    timezone: ['schedule', 'once'],
+    'max-fires-per-day': ['schedule', 'stochastic', 'self_scheduled'],
+    at: ['once'],
+    'next-run-at': ['once', 'self_scheduled'],
+    entity: ['event'],
+    event: ['event'],
+    'filter-mode': ['event'],
+    'filter-field': ['event'],
+    'filter-value': ['event'],
+    'debounce-ms': ['event'],
+    'max-per-hour': ['event'],
+    probability: ['stochastic'],
+    'jitter-ms': ['stochastic'],
+    'eval-interval-minutes': ['stochastic'],
+    'form-title': ['form'],
+    'form-subtitle': ['form'],
+    'form-fields': ['form'],
+    'form-response-mode': ['form'],
+    'thank-you-message': ['form'],
+    'redirect-url': ['form'],
+    'ip-allowlist': ['form'],
+    'ignore-bots': ['form'],
+    'submit-button-label': ['form'],
+    'chat-mode': ['chat_message'],
+    'chat-response-mode': ['chat_message'],
+    'allowed-origin': ['chat_message'],
+    'allow-file-uploads': ['chat_message'],
+    'allowed-mime-types': ['chat_message'],
+    'initial-message': ['chat_message'],
+    'suggested-prompt': ['chat_message'],
+    'input-placeholder': ['chat_message'],
+    'auth-mode': ['chat_message'],
+    'load-previous-session': ['chat_message'],
+    'chat-title': ['chat_message'],
+    'chat-subtitle': ['chat_message'],
+});
+const flagWasPassed = (value) => value !== undefined && value !== null && !(Array.isArray(value) && value.length === 0);
+/**
+ * Refuse a kind-specific flag the trigger's kind cannot use, naming each one and the kinds that
+ * take it. Silence here is the defect: the caller believes a limit is in force.
+ */
+function assertKindFlagsApply(kind, flags, options = {}) {
+    if (typeof kind !== 'string' || !(kind in CONFIG_KEY_BY_TRIGGER_KIND))
+        return;
+    const misplaced = Object.entries(exports.FLAG_OWNER_KINDS).filter(([flag, owners]) => flagWasPassed(flags[flag]) && !owners.includes(kind));
+    if (misplaced.length === 0)
+        return;
+    const named = misplaced.map(([flag, owners]) => `--${flag} (${owners.join(', ')})`);
+    const verb = misplaced.length === 1 ? 'does' : 'do';
+    let subject = `--kind ${kind}`;
+    let fix = ' Remove it, or choose a kind that takes it.';
+    const holdsNothing = !CONFIG_KEY_BY_TRIGGER_KIND[kind];
+    if (options.kindIsFixed) {
+        subject = `this trigger, whose kind is ${kind}`;
+        fix = ' A trigger kind cannot be changed after creation, so remove it.';
+        if (holdsNothing)
+            fix = ` An ${kind} trigger has no per-trigger settings.${fix}`;
+    }
+    else if (holdsNothing) {
+        fix = ` An ${kind} trigger has no per-trigger settings; remove it, or choose a kind that takes it.`;
+    }
+    throw new Error(`${named.join(', ')} ${verb} not apply to ${subject}.${fix}`);
+}
+/**
+ * The sentence for a fire's `scheduledFire` report: what a MANUAL fire skipped that a scheduled
+ * one would not. A manual fire is exempt from the enabled gate, the working/quiet-hours overlay and
+ * the autonomy ladder, so on its own it certifies nothing about whether the trigger will ever fire
+ * by itself (OSK-15492). Absent when the server reported nothing to say.
+ */
+function describeScheduledFire(result) {
+    const report = result.scheduledFire;
+    if (typeof report !== 'object' || report === null)
+        return undefined;
+    const { wouldRun, reason, bypassed } = report;
+    const why = typeof reason === 'string' && reason ? ` (${reason})` : '';
+    if (Array.isArray(bypassed) && bypassed.length > 0) {
+        const gates = bypassed
+            .map((entry) => `${String(entry.gate)}${entry.reason ? ` (${String(entry.reason)})` : ''}`)
+            .join(', ');
+        return `Note: this manual fire bypassed ${gates}; a scheduled fire would not run.`;
+    }
+    if (wouldRun === false) {
+        return `Note: a scheduled fire would not run${why}; a manual fire is exempt from that check.`;
+    }
+    if (wouldRun === null) {
+        return `Note: whether a scheduled fire would run could not be determined${why}.`;
+    }
+    return undefined;
+}
 function withQuery(path, params) {
     const search = new URLSearchParams();
     for (const [key, value] of Object.entries(params)) {

package/dist/lib/widgetCheck.d.ts

@@ -0,0 +1,123 @@
+import { type RenderUiWidgetFenceInput } from '@skrr-ai/data-provider';
+export declare const WIDGET_CHECK_REPORT_VERSION: 1;
+export type WidgetIssueSeverity = 'error' | 'warn';
+export type WidgetIssueSource = 'grammar' | 'schema' | 'limit' | 'syntax' | 'static' | 'content';
+export interface WidgetIssue {
+    severity: WidgetIssueSeverity;
+    source: WidgetIssueSource;
+    /** Stable machine code, for example `fence/invalid-header` or `static/network-api`. */
+    code: string;
+    message: string;
+    fix?: string;
+    /** The part of the widget the finding is about: a section, `header`, `title`, `total`. */
+    section?: string;
+    /**
+     * 1-based. For a `grammar` finding: the line of the INPUT. For a section-level
+     * finding (syntax, static): the line within that section's own text.
+     */
+    line?: number;
+    /** True for static findings: a guess from reading the source, not the sandbox's verdict. */
+    heuristic?: true;
+}
+export type LimitKey = 'css' | 'html' | 'js' | 'total' | 'title' | 'fallback';
+export interface WidgetUsage {
+    /** Characters (UTF-16 code units): what every limit measures. */
+    used: number;
+    max: number;
+    /** Not clamped: a widget at 207% of its limit says 207. */
+    percent: number;
+    over: boolean;
+    /** Set when the parser stopped counting at the cap, so `used` is a floor. */
+    atLeast?: true;
+}
+export type WidgetKind = 'fence' | 'payload' | 'tool-input';
+export interface WidgetReport {
+    id: string;
+    title: string | null;
+    kind: WidgetKind;
+    /** Fence input only: the line of the input where this block starts. */
+    line?: number;
+    /** The widget is final (`complete: true`); false for a refused or cut-off block. */
+    complete: boolean;
+    /**
+     * False when the content was never read (a refused header, a block past the
+     * per-message cap): `bytes` and `limits` are then zeros that mean "unknown",
+     * not "empty".
+     */
+    measured: boolean;
+    /** The ingest would persist it. A refused widget shows an error state instead. */
+    accepted: boolean;
+    /** Accepted AND no error-severity finding (and no warning under `strict`). */
+    ok: boolean;
+    /** UTF-8 bytes, for information. The limits count characters. */
+    bytes: {
+        css: number;
+        html: number;
+        js: number;
+        total: number;
+    };
+    limits: Record<LimitKey, WidgetUsage>;
+    issues: WidgetIssue[];
+}
+export interface WidgetCheckError {
+    code: string;
+    message: string;
+    fix?: string;
+}
+export interface WidgetCheckReport {
+    reportVersion: typeof WIDGET_CHECK_REPORT_VERSION;
+    /** Every widget would be accepted and none has an error-severity finding. */
+    ok: boolean;
+    format: 'fence' | 'json' | 'unknown';
+    widgets: WidgetReport[];
+    /** Problems with the input as a whole (nothing to check, unreadable JSON, too large). */
+    errors: WidgetCheckError[];
+    /** Notes about the input as a whole that do not refuse anything. */
+    warnings: WidgetCheckError[];
+    summary: {
+        widgets: number;
+        accepted: number;
+        ok: number;
+        errors: number;
+        warnings: number;
+    };
+    heuristic: string;
+}
+export declare const WIDGET_CHECK_HEURISTIC_NOTE: string;
+/** More than this is refused unread: six widgets at their caps are about 1.2 MB. */
+export declare const WIDGET_CHECK_MAX_INPUT_CHARS: number;
+export type WidgetCheckFormat = 'auto' | 'fence' | 'json';
+export interface WidgetCheckOptions {
+    format?: WidgetCheckFormat;
+    /** Warnings also make the check fail. */
+    strict?: boolean;
+}
+export interface WidgetCheckResult {
+    report: WidgetCheckReport;
+    /** What `--render-fence` may serialise: only widgets the schema accepted, by index. */
+    renderable: Array<{
+        index: number;
+        input: RenderUiWidgetFenceInput;
+    }>;
+}
+/** The report for an input that could not even be read (a missing file, a terminal as stdin). */
+export declare function inputErrorReport(error: WidgetCheckError): WidgetCheckReport;
+/**
+ * Check one input: a file's text that contains a widget block, or a JSON widget.
+ * Total: never throws, whatever the input.
+ */
+export declare function checkWidgetInput(raw: string, options?: WidgetCheckOptions): WidgetCheckResult;
+export interface RenderedFences {
+    fences: string[];
+    errors: WidgetCheckError[];
+}
+/**
+ * Serialise the JSON widgets that passed the schema to correctly delimited fence
+ * blocks, and prove each one: the block is parsed back with the same parser the
+ * ingest uses and must yield the same title, sections and fallback. The colon
+ * count is chosen by `renderUiWidgetFence`, so a widget whose code contains a line
+ * of colons still gets a closing line it cannot end early.
+ */
+export declare function renderWidgetFences(result: WidgetCheckResult): RenderedFences;
+/** The report as lines of plain text, for a person or a model reading a terminal. */
+export declare function formatWidgetCheckReport(report: WidgetCheckReport): string[];