@skrr-ai/cli 0.1.8

package/dist/lib/triggers.js

@@ -0,0 +1,920 @@
+"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.validateEventReference = validateEventReference;
+exports.validateEventFilter = validateEventFilter;
+exports.serverEventCatalogIncludes = serverEventCatalogIncludes;
+exports.parseKeyValueFlags = parseKeyValueFlags;
+exports.parseJsonObject = parseJsonObject;
+exports.parseJsonArray = parseJsonArray;
+exports.buildBuiltinActionPayload = buildBuiltinActionPayload;
+exports.splitRepeated = splitRepeated;
+exports.buildScheduleConfigFromFlags = buildScheduleConfigFromFlags;
+exports.assertScheduleTimingShape = assertScheduleTimingShape;
+exports.buildOnceConfigFromFlags = buildOnceConfigFromFlags;
+exports.buildSelfScheduledConfigFromFlags = buildSelfScheduledConfigFromFlags;
+exports.buildFormConfigFromFlags = buildFormConfigFromFlags;
+exports.buildChatMessageConfigFromFlags = buildChatMessageConfigFromFlags;
+exports.parseExecutionReferences = parseExecutionReferences;
+exports.parseEmbeddedActions = parseEmbeddedActions;
+exports.assertEmbeddedActionTokensBound = assertEmbeddedActionTokensBound;
+exports.setDefined = setDefined;
+exports.mergeObjectField = mergeObjectField;
+exports.mergeTriggerKindConfig = mergeTriggerKindConfig;
+exports.withQuery = withQuery;
+exports.agentScope = agentScope;
+exports.spaceSubscriberScope = spaceSubscriberScope;
+exports.agentRefEntity = agentRefEntity;
+exports.fetchAgentScopedTrigger = fetchAgentScopedTrigger;
+exports.scopeLabel = scopeLabel;
+exports.nextRunLabel = nextRunLabel;
+exports.renderTriggerList = renderTriggerList;
+exports.formatDuplicateSubscriptionWarning = formatDuplicateSubscriptionWarning;
+exports.armedStateLabel = armedStateLabel;
+exports.writeModeLabel = writeModeLabel;
+exports.renderTriggerSummary = renderTriggerSummary;
+exports.renderLegacyRuns = renderLegacyRuns;
+exports.renderFireAudit = renderFireAudit;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const format_1 = require("./format");
+exports.TRIGGER_KINDS = [
+    'schedule',
+    'once',
+    'event',
+    'stochastic',
+    'self_scheduled',
+    'on_demand',
+    'form',
+    'chat_message',
+];
+exports.TRIGGER_SCOPE_KINDS = [
+    'agent',
+    'group_chat_subscriber',
+    'space_oracle',
+    'space_subscriber',
+    'key_result_watcher',
+    'task_watcher',
+    'goal_watcher',
+    'entity_reminder',
+];
+/**
+ * Executor modes this CLI will let you author.
+ *
+ * A SECOND DECLARATION of a server-owned vocabulary, and it drifts — which is
+ * the whole problem. `@skrr-ai/data-schemas` owns the list, but it pulls
+ * mongoose, and neither this package nor `data-provider` depends on it; bundling
+ * it to read one array would be the wrong trade. So the copy stays and
+ * `__tests__/executor-mode-parity.spec.ts` pins it against the server's source,
+ * turning a silent missing capability into a build failure.
+ *
+ * That test exists because of a real one: `external_work_task` shipped
+ * server-side — storable, registered, allowed, executable — and this list did
+ * not know about it, so `skrr triggers create --mode external_work_task` was
+ * rejected by the CLI's own flag parser before the server ever saw it. The
+ * capability was live and unreachable. `watch_until` and `sensor_poll` had been
+ * in that state for longer.
+ */
+exports.TRIGGER_EXECUTOR_MODES = [
+    'send_message',
+    'run_only',
+    'enqueue_group_chat_agent_turn',
+    'enqueue_assistant_turn',
+    'enqueue_space_assistant_turn',
+    'proactive_orchestrator_check',
+    'auto_dream_orchestrator',
+    'task_schedule_fire',
+    'goal_planner_tick',
+    'morning_briefing',
+    'builtin_action',
+    // User-authorable capabilities the server allows on the agent scope.
+    'watch_until',
+    'sensor_poll',
+    'external_work_task',
+    'notify_user',
+    'space_cycle_rollover',
+];
+exports.TRIGGER_EVENT_FILTER_MODES = ['equals', 'contains', 'in_set'];
+exports.TRIGGER_CONCURRENCY_POLICIES = ['coalesce_if_active', 'allow_parallel'];
+exports.TRIGGER_FORM_RESPONSE_MODES = [
+    'thank_you_page',
+    'redirect_url',
+    'run_complete',
+];
+exports.TRIGGER_CHAT_MODES = ['hosted', 'embed', 'webhook'];
+exports.TRIGGER_CHAT_RESPONSE_MODES = ['streaming', 'last_message', 'run_complete'];
+exports.TRIGGER_CHAT_AUTH_MODES = ['none', 'basic', 'workspace_user'];
+/**
+ * Canonical event catalog — mirrors `api/server/services/EventBus/schemas`.
+ *
+ * Server‑side Zod is the source of truth; the CLI uses this table to fail
+ * fast on typos and to render a helpful "did you mean…" suggestion. Pass
+ * `--allow-unknown-event` to bypass when authoring a brand‑new event type
+ * that the CLI hasn't been updated for yet.
+ *
+ * ADVISORY, NOT A GATE. This list drifts — it knew 6 entity types while the
+ * server routed 15, so every external-provider event (github, slack, gmail,
+ * composio) was unreachable from the CLI: `--entity github` was rejected by the
+ * CLI's own parser before the server was ever asked, for events the server had
+ * declared all along.
+ *
+ * Blocking on a stale local copy trades a round-trip for an unreachable
+ * capability, which is the wrong way round. The server is the authority and
+ * already validates (`EVENT_TYPE_UNDECLARED`), so an entry missing here now
+ * costs a warning and the request still goes. `skrr triggers event-catalog` asks
+ * the server what it actually declares.
+ */
+exports.TRIGGER_EVENT_ENTITY_TYPES = [
+    'task',
+    'space',
+    'goal',
+    'key_result',
+    'group',
+    'cloud_coding',
+];
+exports.TRIGGER_EVENT_CATALOG = {
+    task: [
+        'task.created',
+        'task.updated',
+        'task.status_changed',
+        'task.priority_changed',
+        'task.assigned',
+        'task.completed',
+        'task.archived',
+    ],
+    space: [
+        'space.created',
+        'space.updated',
+        'space.archived',
+        'space.member_added',
+        'space.member_removed',
+    ],
+    goal: ['goal.created', 'goal.updated', 'goal.completed', 'goal.archived'],
+    key_result: [
+        'key_result.created',
+        'key_result.updated',
+        'key_result.progress_changed',
+        'key_result.target_changed',
+        'key_result.completed',
+    ],
+    group: ['group.message.saved', 'group.message.mentioned', 'group.message.keyword_matched'],
+    cloud_coding: ['cloud_coding.task.transitioned'],
+};
+/**
+ * Levenshtein distance (small, dependency‑free) — used only to suggest a
+ * close match when the user typos an event name. Cap input lengths so a
+ * pathological flag value can't burn CPU.
+ */
+function editDistance(a, b) {
+    const al = Math.min(a.length, 64);
+    const bl = Math.min(b.length, 64);
+    if (al === 0)
+        return bl;
+    if (bl === 0)
+        return al;
+    const prev = new Array(bl + 1);
+    const curr = new Array(bl + 1);
+    for (let j = 0; j <= bl; j += 1)
+        prev[j] = j;
+    for (let i = 1; i <= al; i += 1) {
+        curr[0] = i;
+        for (let j = 1; j <= bl; j += 1) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j <= bl; j += 1)
+            prev[j] = curr[j];
+    }
+    return prev[bl];
+}
+function closestEventSuggestion(entityType, eventType) {
+    const candidates = exports.TRIGGER_EVENT_CATALOG[entityType] ?? [];
+    let best;
+    for (const candidate of candidates) {
+        const distance = editDistance(eventType.toLowerCase(), candidate.toLowerCase());
+        if (!best || distance < best.distance)
+            best = { value: candidate, distance };
+    }
+    if (!best)
+        return undefined;
+    // 3 is the maximum Levenshtein distance we'll surface — past that the
+    // suggestion is noise, not help.
+    return best.distance <= 3 ? best.value : undefined;
+}
+/**
+ * Validate `--entity` + `--event` against the canonical catalog. Throws on
+ * mismatch unless `allowUnknown` is true (the user opted in via
+ * `--allow-unknown-event`).
+ *
+ * Returns silently when validation passes, when the trigger isn't an event
+ * kind (`entityType`/`eventType` undefined), or when only one half is
+ * supplied (incomplete patches on `update`).
+ */
+function validateEventReference(entityType, eventType, options = {}) {
+    if (!entityType || !eventType)
+        return null;
+    if (options.allowUnknown)
+        return null;
+    const entities = exports.TRIGGER_EVENT_ENTITY_TYPES;
+    if (!entities.includes(entityType)) {
+        // The CLI ships a snapshot of the entity list and is versioned separately
+        // from the server, so this list runs BEHIND — `github` is declared by the
+        // server today and absent here. Presenting the local list as the standard
+        // the input failed made a correct `--entity github` look like a typo, on one
+        // of the main documented uses of event triggers, and then pointed at
+        // `event-catalog`, which prints the entity and disproves the warning.
+        //
+        // Lead with what is true (this is a local gap, the create is proceeding) and
+        // offer the catalog as confirmation rather than as a contradiction.
+        return (`Event entity "${entityType}" is not in this CLI's built-in list (it knows: ` +
+            `${exports.TRIGGER_EVENT_ENTITY_TYPES.join(', ')}), which may be behind this server. ` +
+            `Sending anyway — the server validates event types and will reject an unknown one. ` +
+            `Run \`skrr triggers event-catalog\` to see what this server declares.`);
+    }
+    const catalog = exports.TRIGGER_EVENT_CATALOG[entityType];
+    if (catalog.includes(eventType))
+        return null;
+    const suggestion = closestEventSuggestion(entityType, eventType);
+    const hint = suggestion ? ` Did you mean "${suggestion}"?` : '';
+    return (`Event "${eventType}" is not in this CLI's built-in list for entity "${entityType}", ` +
+        `which may be behind this server.${hint} ` +
+        `Sending anyway — the server validates and will reject it if it is wrong.`);
+}
+/**
+ * Validate that `--filter-mode` and `--filter-value` agree:
+ *   - `equals` and `contains` take a single value.
+ *   - `in_set` requires one or more values; we send an array when ≥2.
+ *
+ * Always allows the "no filter at all" case (both unset) so partial event
+ * configs on `update` don't trip this check.
+ */
+function validateEventFilter(input) {
+    const { filterMode, filterField, filterValues } = input;
+    const values = filterValues ?? [];
+    // No filter at all → fine. The server treats an event trigger with no
+    // filter as "match every event of (entityType, eventType)".
+    if (!filterMode && !filterField && values.length === 0)
+        return;
+    // A field with no mode defaults to `equals` server‑side, so don't reject;
+    // the server enforces the shape. We only police obvious contradictions.
+    if (filterMode && !exports.TRIGGER_EVENT_FILTER_MODES.includes(filterMode)) {
+        throw new Error(`Invalid --filter-mode "${filterMode}". Valid modes: ${exports.TRIGGER_EVENT_FILTER_MODES.join(', ')}.`);
+    }
+    if (filterMode === 'in_set') {
+        if (values.length < 1) {
+            throw new Error('Filter mode "in_set" requires one or more --filter-value flags ' +
+                '(repeatable or comma-separated).');
+        }
+        if (!filterField) {
+            throw new Error('Filter mode "in_set" requires --filter-field.');
+        }
+        return;
+    }
+    if (filterMode === 'contains' || filterMode === 'equals') {
+        if (values.length > 1) {
+            throw new Error(`Filter mode "${filterMode}" accepts a single --filter-value. ` +
+                `Pass --filter-mode in_set to match against multiple values.`);
+        }
+        if (values.length === 1 && !filterField) {
+            throw new Error(`Filter mode "${filterMode}" requires --filter-field.`);
+        }
+        return;
+    }
+    // No --filter-mode specified but values present — server defaults to
+    // `equals`. Reject multiple values to be explicit.
+    if (values.length > 1) {
+        throw new Error('Multiple --filter-value flags require --filter-mode in_set. ' +
+            'Pass an explicit --filter-mode to disambiguate.');
+    }
+    if (values.length === 1 && !filterField) {
+        throw new Error('--filter-value requires --filter-field.');
+    }
+}
+/** Whether the live server declares this exact event reference. */
+function serverEventCatalogIncludes(catalog, entityType, eventType) {
+    if (!catalog || !entityType || !eventType)
+        return false;
+    return (catalog.events ?? []).some((entry) => entry.entityType === entityType && entry.eventType === eventType);
+}
+/**
+ * The one ref key a scope kind implies, for the scopes that have exactly one.
+ *
+ * `--scope agent --ref agent_abc` is unambiguous: an agent-scoped trigger takes
+ * an `agentId` and nothing else, so making the user restate it as
+ * `--ref agentId=agent_abc` is ceremony. The scopes NOT listed here take two or
+ * three refs (`task_watcher` needs `taskId` AND `watcherAgentId`), where a bare
+ * value really is ambiguous and must stay explicit.
+ *
+ * Keys mirror what the server's resolvers read — see
+ * `api/server/services/TriggerEngine/resolvers/*.js`.
+ */
+exports.SCOPE_IMPLIED_REF_KEY = {
+    agent: 'agentId',
+    space_oracle: 'spaceId',
+    goal_watcher: 'goalId',
+    group_chat_subscriber: 'groupChatId',
+};
+/** Ref keys each multi-ref scope expects, so the error can name them. */
+const SCOPE_EXPECTED_REF_KEYS = {
+    task_watcher: ['taskId', 'watcherAgentId'],
+    key_result_watcher: ['keyResultId', 'watcherAgentId'],
+    space_subscriber: ['spaceId', 'agentId', 'subscriberUserId'],
+};
+function parseKeyValueFlags(values, flagName, scopeKind) {
+    const refs = {};
+    const impliedKey = scopeKind ? exports.SCOPE_IMPLIED_REF_KEY[scopeKind] : undefined;
+    for (const raw of values ?? []) {
+        const idx = raw.indexOf('=');
+        if (idx <= 0 || idx === raw.length - 1) {
+            const bare = raw.trim();
+            // A bare value is accepted only when the scope names exactly one ref key.
+            if (impliedKey && bare && !bare.includes('=')) {
+                refs[impliedKey] = bare;
+                continue;
+            }
+            const expected = scopeKind && SCOPE_EXPECTED_REF_KEYS[scopeKind]
+                ? ` — scope "${scopeKind}" takes ${SCOPE_EXPECTED_REF_KEYS[scopeKind].map((k) => `${k}=<id>`).join(' and ')}`
+                : '';
+            throw new Error(`${flagName} values must use key=value, got "${raw}"${expected}`);
+        }
+        const key = raw.slice(0, idx).trim();
+        const value = raw.slice(idx + 1).trim();
+        if (!key || !value) {
+            throw new Error(`${flagName} values must use key=value, got "${raw}"`);
+        }
+        refs[key] = value;
+    }
+    return refs;
+}
+function parseJsonObject(raw, flagName) {
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid ${flagName} JSON: ${msg}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${flagName} must be a JSON object`);
+    }
+    return parsed;
+}
+function parseJsonArray(raw, flagName) {
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid ${flagName} JSON: ${msg}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`${flagName} must be a JSON array`);
+    }
+    return parsed;
+}
+function buildBuiltinActionPayload(input) {
+    const direct = parseJsonObject(input.builtinAction, '--builtin-action');
+    const config = parseJsonObject(input.builtinConfig, '--builtin-config');
+    const payload = { ...(direct ?? {}) };
+    setDefined(payload, {
+        builtinType: input.builtinType,
+        config,
+        sourceActionId: input.sourceActionId,
+        nudgePrompt: input.nudgePrompt,
+    });
+    return Object.keys(payload).length > 0 ? payload : undefined;
+}
+function splitRepeated(values) {
+    const out = (values ?? [])
+        .flatMap((v) => v.split(','))
+        .map((v) => v.trim())
+        .filter((v) => v.length > 0);
+    return out.length > 0 ? out : undefined;
+}
+function buildScheduleConfigFromFlags(flags) {
+    const dailyTimes = splitRepeated(flags['daily-time']);
+    const intervalMs = typeof flags['interval-ms'] === 'number'
+        ? flags['interval-ms']
+        : typeof flags['interval-minutes'] === 'number'
+            ? flags['interval-minutes'] * 60_000
+            : undefined;
+    const schedule = {};
+    setDefined(schedule, {
+        cronExpression: flags.cron,
+        intervalMs,
+        times: dailyTimes,
+        timezone: flags.timezone,
+        maxFiresPerDay: flags['max-fires-per-day'] ?? flags['max-per-day'],
+        maxRuns: flags['max-runs'],
+        endAt: flags['end-at'],
+        staleCatchupMs: flags['stale-catchup-ms'],
+    });
+    return schedule;
+}
+function assertScheduleTimingShape(schedule, options = {}) {
+    const timingCount = [schedule?.cronExpression, schedule?.intervalMs, schedule?.times].filter((value) => value !== undefined && value !== null).length;
+    if (timingCount > 1) {
+        throw new Error('Schedule triggers accept exactly one timing source: --cron, --interval-ms/--interval-minutes, or --daily-time.');
+    }
+    if (options.requireTiming && timingCount === 0) {
+        throw new Error(options.flagHint ?? '--kind schedule requires --cron, --interval-minutes, or --daily-time.');
+    }
+}
+function buildOnceConfigFromFlags(flags, options = {}) {
+    const runAt = flags.at ??
+        (options.allowNextRunAtAlias && options.kind === 'once' ? flags['next-run-at'] : undefined);
+    const once = {};
+    setDefined(once, {
+        runAt,
+        timezone: flags.timezone,
+    });
+    return once;
+}
+function buildSelfScheduledConfigFromFlags(flags) {
+    const selfScheduled = {};
+    setDefined(selfScheduled, {
+        nextRunAt: flags['next-run-at'],
+        maxFiresPerDay: flags['max-fires-per-day'],
+    });
+    return selfScheduled;
+}
+function buildFormConfigFromFlags(flags) {
+    const form = {};
+    const fields = parseJsonArray(flags['form-fields'], '--form-fields');
+    setDefined(form, {
+        title: flags['form-title'],
+        subtitle: flags['form-subtitle'],
+        fields,
+        responseMode: flags['form-response-mode'],
+        thankYouMessage: flags['thank-you-message'],
+        redirectUrl: flags['redirect-url'],
+        ipAllowlist: splitRepeated(flags['ip-allowlist']),
+        ignoreBots: flags['ignore-bots'],
+        submitButtonLabel: flags['submit-button-label'],
+    });
+    return form;
+}
+function buildChatMessageConfigFromFlags(flags) {
+    const chatMessage = {};
+    setDefined(chatMessage, {
+        mode: flags['chat-mode'],
+        allowedOrigins: splitRepeated(flags['allowed-origin']),
+        allowFileUploads: flags['allow-file-uploads'],
+        allowedMimeTypes: flags['allowed-mime-types'],
+        initialMessages: splitRepeated(flags['initial-message']),
+        suggestedPrompts: splitRepeated(flags['suggested-prompt']),
+        inputPlaceholder: flags['input-placeholder'],
+        responseMode: flags['chat-response-mode'],
+        authMode: flags['auth-mode'],
+        loadPreviousSession: flags['load-previous-session'],
+        title: flags['chat-title'],
+        subtitle: flags['chat-subtitle'],
+    });
+    return chatMessage;
+}
+function parseExecutionReferences(referenceValues, referencesJson) {
+    const out = [];
+    const parsedJson = parseJsonArray(referencesJson, '--references');
+    if (parsedJson) {
+        for (const item of parsedJson) {
+            if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+                throw new Error('--references entries must be JSON objects');
+            }
+            out.push(item);
+        }
+    }
+    for (const raw of referenceValues ?? []) {
+        const parts = raw.split(':');
+        const kind = parts.shift()?.trim();
+        const id = parts.shift()?.trim();
+        const label = parts.length > 0 ? parts.join(':').trim() : undefined;
+        if (!kind || !id) {
+            throw new Error(`--reference values must use kind:id[:label], got "${raw}"`);
+        }
+        if (!['goal', 'task', 'space', 'groupChat'].includes(kind)) {
+            throw new Error(`Invalid --reference kind "${kind}". Valid kinds: goal, task, space, groupChat.`);
+        }
+        out.push({
+            kind,
+            id,
+            ...(label ? { label } : {}),
+        });
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Parse `--embed refId=builtinType[:configJson]` flags (repeatable) and/or an
+ * `--embeds <jsonArray>` into the structured `embeddedActions[]` — the chip
+ * source of truth. Validated through the SHARED `normalizeEmbeddedActions`, so a
+ * CLI-authored embedded action and a UI-authored one are byte-identical and the
+ * frontend re-hydrates the same chip. Throws on a bad shape / unknown subtype.
+ */
+function parseEmbeddedActions(embedValues, embedsJson) {
+    const raw = [];
+    const parsedJson = parseJsonArray(embedsJson, '--embeds');
+    if (parsedJson) {
+        for (const item of parsedJson) {
+            if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+                throw new Error('--embeds entries must be JSON objects');
+            }
+            raw.push(item);
+        }
+    }
+    for (const value of embedValues ?? []) {
+        const eq = value.indexOf('=');
+        if (eq < 0) {
+            throw new Error(`--embed values must use refId=builtinType[:configJson], got "${value}"`);
+        }
+        const refId = value.slice(0, eq).trim();
+        const rest = value.slice(eq + 1).trim();
+        const colon = rest.indexOf(':');
+        const builtinType = (colon < 0 ? rest : rest.slice(0, colon)).trim();
+        const configRaw = colon < 0 ? '' : rest.slice(colon + 1).trim();
+        if (!refId || !builtinType) {
+            throw new Error(`--embed values must use refId=builtinType[:configJson], got "${value}"`);
+        }
+        let config = {};
+        if (configRaw) {
+            let parsed;
+            try {
+                parsed = JSON.parse(configRaw);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`--embed config for "${refId}" must be valid JSON: ${message}`);
+            }
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                throw new Error(`--embed config for "${refId}" must be a JSON object.`);
+            }
+            config = parsed;
+        }
+        raw.push({ refId, builtinType, config });
+    }
+    // Shared contract enforces the cap, dedupe, and known-subtype check.
+    return (0, data_provider_1.normalizeEmbeddedActions)(raw);
+}
+/**
+ * Enforce the inline-token contract: an embedded built-in action is MIXED INTO
+ * the prompt at its `[[action:<refId>]]` token (the workflow position), and each
+ * `--embed <refId>=…` binding supplies its config. Every token must have a
+ * binding and every binding must have a token — otherwise the chip is unplaced
+ * (binding without token) or unbound (token without config). The server expands
+ * each token to its instruction at run time, so the prompt is stored with the
+ * tokens intact (NOT baked).
+ */
+function assertEmbeddedActionTokensBound(prompt, embeds) {
+    const tokenRefIds = new Set((0, data_provider_1.parseEmbeddedActionTokenRefIds)(prompt));
+    const bindingRefIds = new Set((embeds ?? []).map((embed) => embed.refId));
+    for (const refId of tokenRefIds) {
+        if (!bindingRefIds.has(refId)) {
+            throw new Error(`Prompt contains [[action:${refId}]] but no --embed ${refId}=<builtinType>[:configJson] binding was provided.`);
+        }
+    }
+    for (const refId of bindingRefIds) {
+        if (!tokenRefIds.has(refId)) {
+            throw new Error(`--embed ${refId}=… has no [[action:${refId}]] placeholder in the prompt. ` +
+                'Put the token where the action should run in the workflow.');
+        }
+    }
+}
+function setDefined(target, values) {
+    for (const [key, value] of Object.entries(values)) {
+        if (value !== undefined)
+            target[key] = value;
+    }
+}
+function mergeObjectField(target, key, values) {
+    if (!values || Object.keys(values).length === 0)
+        return;
+    const existing = typeof target[key] === 'object' && target[key] !== null && !Array.isArray(target[key])
+        ? target[key]
+        : {};
+    target[key] = { ...existing, ...values };
+}
+const CONFIG_KEY_BY_TRIGGER_KIND = Object.freeze({
+    on_demand: undefined,
+    schedule: 'schedule',
+    once: 'once',
+    event: 'event',
+    stochastic: 'stochastic',
+    self_scheduled: 'selfScheduled',
+    form: 'form',
+    chat_message: 'chatMessage',
+});
+/** Attach only the discriminator subdocument owned by `kind`. */
+function mergeTriggerKindConfig(target, kind, configs) {
+    if (typeof kind !== 'string')
+        return;
+    const key = CONFIG_KEY_BY_TRIGGER_KIND[kind];
+    if (!key)
+        return;
+    mergeObjectField(target, key, configs[key]);
+}
+function withQuery(path, params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                search.append(key, item);
+        }
+        else {
+            search.set(key, String(value));
+        }
+    }
+    const suffix = search.toString();
+    return suffix ? `${path}?${suffix}` : path;
+}
+/**
+ * Build the universal-engine scope block for an agent-owned trigger.
+ *
+ * The per-agent `/api/agents/:id/triggers` route is a deprecated facade; the
+ * canonical authoring surface is the universal Trigger Engine with an `agent`
+ * scope. The `skrr agents triggers …` / `skrr agents schedule …` commands inject
+ * this so callers never have to hand-assemble `--scope agent --ref agentId=…`.
+ */
+function agentScope(agentId) {
+    return { kind: 'agent', refs: { agentId } };
+}
+/**
+ * Build the universal-engine scope block for a per-agent, per-space schedule.
+ *
+ * A `space_subscriber` trigger runs `agentId` inside `spaceId` on behalf of
+ * `subscriberUserId` (the authenticated caller). This mirrors the web Schedule
+ * Board's "space mode" authoring path, and must pair with the
+ * `enqueue_space_assistant_turn` execution mode the spaceSubscriber resolver
+ * requires — see `api/server/services/TriggerEngine/resolvers/spaceSubscriber.js`.
+ */
+function spaceSubscriberScope(spaceId, subscriberUserId, agentId) {
+    return { kind: 'space_subscriber', refs: { spaceId, subscriberUserId, agentId } };
+}
+/**
+ * `ref-entity` filter token for listing an agent's universal triggers
+ * (`GET /api/triggers?refEntity=agent:<id>`). Mirrors the `kind:id` form the
+ * `triggers list --ref-entity` flag accepts.
+ */
+function agentRefEntity(agentId) {
+    return `agent:${agentId}`;
+}
+/**
+ * Raised when a `skrr agents triggers <verb> <agent-id> <trigger-id>` command is
+ * pointed at a trigger that isn't agent-scoped to that agent. Lets the
+ * agent-scoped lifecycle commands be genuinely scoped (a safety fence against
+ * fat-fingering another agent's trigger id) rather than thin global aliases.
+ */
+class AgentTriggerScopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentTriggerScopeError';
+    }
+}
+exports.AgentTriggerScopeError = AgentTriggerScopeError;
+/**
+ * Fetch a trigger and assert it is `scope.kind==='agent'` bound to `agentId`.
+ * Returns the fetched definition (so callers rendering it — show / runs —
+ * avoid a second GET). Throws {@link AgentTriggerScopeError} on mismatch.
+ */
+async function fetchAgentScopedTrigger(agentId, triggerId) {
+    const trigger = await exports.triggerApi.get(triggerId);
+    const scopedAgentId = trigger.scope?.refs?.agentId;
+    if (trigger.scope?.kind !== 'agent' || scopedAgentId !== agentId) {
+        throw new AgentTriggerScopeError(`Trigger ${triggerId} is not an agent-scoped trigger for agent ${agentId}` +
+            `${scopedAgentId ? ` (it belongs to agent ${String(scopedAgentId)})` : ''}. ` +
+            `Use \`skrr triggers <verb> ${triggerId}\` to operate on it regardless of scope.`);
+    }
+    return trigger;
+}
+function scopeLabel(trigger) {
+    const kind = trigger.scope?.kind ?? '-';
+    const refs = trigger.scope?.refs ?? {};
+    const refText = Object.entries(refs)
+        .map(([k, v]) => `${k}=${String(v)}`)
+        .join(',');
+    return refText ? `${kind}:${refText}` : kind;
+}
+function nextRunLabel(trigger) {
+    const next = trigger.schedule?.nextRunAt ??
+        trigger.selfScheduled?.nextRunAt ??
+        trigger.audit?.lastFiredAt ??
+        '';
+    return next ? String(next) : '-';
+}
+function renderTriggerList(triggers, log) {
+    if (triggers.length === 0) {
+        log('No triggers.');
+        return;
+    }
+    (0, format_1.renderTable)(triggers.map((trigger) => ({
+        id: trigger.id ?? '-',
+        kind: trigger.kind ?? '-',
+        enabled: trigger.enabled === false ? 'no' : 'yes',
+        scope: scopeLabel(trigger),
+        next: nextRunLabel(trigger),
+        label: trigger.label ?? '',
+    })), [
+        { key: 'id', header: 'ID', verbatim: true },
+        { key: 'kind', header: 'KIND', maxWidth: 14 },
+        { key: 'enabled', header: 'ON' },
+        { key: 'scope', header: 'SCOPE', maxWidth: 42 },
+        { key: 'next', header: 'NEXT/LAST', maxWidth: 24 },
+        { key: 'label', header: 'LABEL', maxWidth: 32 },
+    ], log);
+}
+/**
+ * The `duplicate_subscription` warning a create response may carry, as the
+ * lines to print.
+ *
+ * A pure function rather than logic inside the command so the wording is
+ * testable: the server creates the trigger and then says whether something
+ * already watches the same thing, and getting that sentence wrong is the whole
+ * reason the warning exists.
+ *
+ * Returns null when the response carries no such warning, which is the common
+ * case and must stay silent.
+ */
+function formatDuplicateSubscriptionWarning(trigger) {
+    const warnings = trigger?.warnings;
+    if (!Array.isArray(warnings))
+        return null;
+    const found = warnings.find((w) => w?.code === 'duplicate_subscription');
+    if (!found)
+        return null;
+    const duplicates = Array.isArray(found.duplicates) ? found.duplicates : [];
+    const lines = duplicates.map((dup) => {
+        const events = Array.isArray(dup.eventTypes) ? dup.eventTypes.join(', ') : '';
+        const label = dup.label ? ` "${String(dup.label)}"` : '';
+        return `  also fires: ${String(dup.id)}${label}${events ? ` — on ${events}` : ''}`;
+    });
+    return {
+        warning: String(found.message ?? 'Another subscription already watches this.'),
+        lines,
+    };
+}
+/**
+ * Human phrasing for a trigger's enabled state (OSK-4886).
+ *
+ * `Enabled:  yes` never used the vocabulary the create flow does — a trigger is
+ * "armed" when it will fire and "inert" until enabled — so a freshly-created
+ * trigger did not plainly confirm it is live.
+ */
+function armedStateLabel(enabled) {
+    return enabled === false ? 'no — inert until enabled' : 'yes — will fire';
+}
+/**
+ * Human phrasing for an effect trigger's write mode (OSK-4886).
+ *
+ * Rendered raw, `Writes:   approval_required` reads as "it writes the value
+ * approval_required" — but it is HOW the projected effect reaches the outside
+ * system, not what is written. Describe the manner and keep the raw code in
+ * parentheses for scripts.
+ */
+function writeModeLabel(writeMode) {
+    switch (writeMode) {
+        case 'approval_required':
+            return `held for your approval before posting (${writeMode})`;
+        case 'bounded_auto_post':
+            return `posted automatically within its bounds (${writeMode})`;
+        default:
+            return writeMode;
+    }
+}
+function renderTriggerSummary(trigger, log) {
+    log(`ID:       ${trigger.id ?? '-'}`);
+    log(`Kind:     ${trigger.kind ?? '-'}`);
+    log(`Armed:    ${armedStateLabel(trigger.enabled)}`);
+    log(`Scope:    ${scopeLabel(trigger)}`);
+    if (trigger.label)
+        log(`Label:    ${trigger.label}`);
+    if (trigger.execution?.mode)
+        log(`Mode:     ${String(trigger.execution.mode)}`);
+    // An `external_work_task` writes into someone else's system, and which
+    // contract governs that write — and whether it posts by itself — was readable
+    // only by pulling `execution.effectPolicy` out of raw JSON. A trigger that can
+    // act on the outside world should say so at the moment it is created.
+    const effect = trigger.execution
+        ?.effectPolicy;
+    if (effect?.contract)
+        log(`Contract: ${String(effect.contract)}`);
+    if (effect?.writeMode)
+        log(`Writes:   ${writeModeLabel(String(effect.writeMode))}`);
+    const next = nextRunLabel(trigger);
+    if (next !== '-')
+        log(`Next/last:${next.length > 0 ? ` ${next}` : ''}`);
+    if (trigger.webhook?.configured !== undefined) {
+        log(`Webhook:  ${trigger.webhook.configured ? 'configured' : 'not configured'}`);
+    }
+}
+function renderLegacyRuns(runs, log) {
+    if (runs.length === 0) {
+        log('No legacy runs.');
+        return;
+    }
+    (0, format_1.renderTable)(runs.map((run) => ({
+        triggered: run.triggeredAt ?? '-',
+        status: run.status ?? '-',
+        source: run.source ?? '-',
+        duration: run.durationMs === undefined ? '-' : `${run.durationMs}ms`,
+        reason: run.failureReason ?? run.skipReason ?? '',
+        conversation: run.conversationId ?? '',
+    })), [
+        { key: 'triggered', header: 'TRIGGERED AT', maxWidth: 24 },
+        { key: 'status', header: 'STATUS', maxWidth: 12 },
+        { key: 'source', header: 'SOURCE', maxWidth: 14 },
+        { key: 'duration', header: 'DURATION', maxWidth: 10 },
+        { key: 'reason', header: 'REASON', maxWidth: 32 },
+        { key: 'conversation', header: 'CONVO', maxWidth: 24 },
+    ], log);
+}
+function renderFireAudit(fires, log) {
+    if (fires.length === 0) {
+        log('No fire audit records.');
+        return;
+    }
+    (0, format_1.renderTable)(fires.map((fire) => ({
+        trigger: fire.triggerId ?? '',
+        firedAt: fire.firedAt ?? '-',
+        outcome: fire.outcome ?? '-',
+        source: fire.source ?? '-',
+        reason: fire.reason ?? fire.errorMessage ?? '',
+        duration: fire.durationMs === undefined ? '-' : `${fire.durationMs}ms`,
+        replay: fire.metadata?.replayable === true || fire.metadata?.replayContext
+            ? 'yes'
+            : fire.outcome === 'pending'
+                ? '-'
+                : `no:${fire.metadata?.replayBlockedReason || 'event_context_required'}`,
+    })), [
+        { key: 'trigger', header: 'TRIGGER', maxWidth: 28 },
+        { key: 'firedAt', header: 'FIRED AT', maxWidth: 24 },
+        { key: 'outcome', header: 'OUTCOME', maxWidth: 18 },
+        { key: 'source', header: 'SOURCE', maxWidth: 18 },
+        { key: 'duration', header: 'DURATION', maxWidth: 10 },
+        { key: 'replay', header: 'REPLAY', maxWidth: 36 },
+        { key: 'reason', header: 'REASON', maxWidth: 40 },
+    ], log);
+}
+exports.triggerApi = {
+    create: (body) => data_provider_1.request.post('/api/triggers', body),
+    list: (path) => data_provider_1.request.get(path),
+    eventCatalog: () => data_provider_1.request.get('/api/triggers/event-catalog'),
+    parseIntent: (body) => data_provider_1.request.post('/api/triggers/parse-intent', body),
+    get: (id) => data_provider_1.request.get(`/api/triggers/${encodeURIComponent(id)}`),
+    update: (id, body) => data_provider_1.request.patch(`/api/triggers/${encodeURIComponent(id)}`, body),
+    setEnabled: (id, enabled) => data_provider_1.request.patch(`/api/triggers/${encodeURIComponent(id)}/enabled`, {
+        enabled,
+    }),
+    delete: (id) => data_provider_1.request.delete(`/api/triggers/${encodeURIComponent(id)}`),
+    fire: (id, body) => data_provider_1.request.post(`/api/triggers/${encodeURIComponent(id)}/fire-now`, body),
+    /**
+     * Dry-run: per-gate verdicts, rendered prompt, resolved destination and the
+     * next projected fires — without firing (gap analysis §A3).
+     *
+     * The distinction from `fire` is the point. `fire-now` stamps
+     * `source: 'manual'`, which takes an autonomy-ladder carve-out, so it can
+     * report success on a trigger whose scheduled path is blocked 100% of the
+     * time. Preflight runs the same gates the real path runs.
+     */
+    preflight: (id, body = {}) => data_provider_1.request.post(`/api/triggers/${encodeURIComponent(id)}/preflight`, body),
+    audit: (path) => data_provider_1.request.get(path),
+    /**
+     * Single fire detail — the universal engine's per-occurrence record
+     * (`GET /api/triggers/:id/fires/:fireId`). `fireId` accepts either the
+     * row's `_id` or its `occurrenceId`. Powers the agent Schedule Board's
+     * TriggerFireDetailModal (outcome + embedded conversation reference).
+     */
+    fireDetail: async (triggerId, fireId) => {
+        const response = (await data_provider_1.request.get(`/api/triggers/${encodeURIComponent(triggerId)}/fires/${encodeURIComponent(fireId)}`));
+        return response.fire ?? response;
+    },
+    replayFire: (triggerId, fireId, body) => data_provider_1.request.post(`/api/triggers/${encodeURIComponent(triggerId)}/fires/${encodeURIComponent(fireId)}/replay`, body),
+    /**
+     * Legacy per-agent runs feed. Reads from the legacy `/api/agents/:agentId/
+     * triggers/:triggerId/runs` route, which queries the `AgentTriggerRun`
+     * collection. Surfaced for back-compat debugging only; the universal audit
+     * (`/api/triggers/:id/audit`) is the source of truth going forward.
+     */
+    legacyRuns: (agentId, triggerId, params) => data_provider_1.request.get(withQuery(`/api/agents/${encodeURIComponent(agentId)}/triggers/${encodeURIComponent(triggerId)}/runs`, params)),
+    /**
+     * Remaining trigger budget for a scope, without attempting a write. The
+     * companion to `prune` — see `TriggerQuotaStatus`.
+     */
+    quota: (params) => data_provider_1.request.get(withQuery('/api/triggers/quota', params)),
+    /** Soft-delete the DISABLED triggers in a scope. Requires `confirm: true`. */
+    prune: (body) => data_provider_1.request.post('/api/triggers/prune', { ...body, confirm: true }),
+    capabilities: (scope) => data_provider_1.request.get(`/api/triggers/scope-capabilities?scope=${encodeURIComponent(scope)}`),
+    agentPolicy: (agentId, auditLimit) => data_provider_1.request.get(withQuery(`/api/triggers/agent-policy/${encodeURIComponent(agentId)}`, {
+        auditLimit,
+    })),
+    updateAgentPolicy: (agentId, body) => data_provider_1.request.patch(`/api/triggers/agent-policy/${encodeURIComponent(agentId)}`, body),
+    rotateSecret: (id) => data_provider_1.request.post(`/api/triggers/${encodeURIComponent(id)}/rotate-webhook-secret`, {}),
+    getGcsPreset: (groupChatId) => data_provider_1.request.get(`/api/triggers/gcs-preset?groupChatId=${encodeURIComponent(groupChatId)}`),
+    setGcsPreset: (body) => data_provider_1.request.put('/api/triggers/gcs-preset', body),
+    getSpaceAssistant: (spaceId) => data_provider_1.request.get(`/api/spaces/${encodeURIComponent(spaceId)}/assistant`),
+    setSpaceAssistant: (spaceId, body) => data_provider_1.request.put(`/api/spaces/${encodeURIComponent(spaceId)}/assistant`, body),
+    deleteSpaceAssistant: (spaceId) => data_provider_1.request.delete(`/api/spaces/${encodeURIComponent(spaceId)}/assistant`),
+};