@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/compute-host/source-compute-host.d.ts

@@ -1,14 +1,14 @@
-import { type CaseContextViewFn } from '../core/functions/define/case-context.js';
+import { type AnyEventHandlers } from '../core/functions/events.js';
 import type { FuncMap } from '../core/functions/types.js';
 import type { ComputeHost } from './compute-host.js';
-import type { RuntimeSlotsSnapshot } from '../core/slot/types.js';
-import type { ActionDataSlice, ApiHost } from '../fn-context/types.js';
+import type { ActionDataSlice, ApiHost, CaseOrchestratorApiHost } from '../fn-context/types.js';
 export type SourceComputeHostOptions = {
     functions: FuncMap;
-    caseContextView?: CaseContextViewFn<RuntimeSlotsSnapshot, unknown>;
+    /** Company `events` export; handlers are registered under the event name. */
+    events?: AnyEventHandlers;
     /** Override ApiHost; default Fake, or Rpc when runToken + data.config.backendUrl. */
-    apiHost?: ApiHost;
-    /** ActionDataSlice used to build ctx for custom / system. */
+    apiHost?: ApiHost & CaseOrchestratorApiHost;
+    /** ActionDataSlice used to build every function's ctx. */
     data?: ActionDataSlice;
     /** When set with data.config.backendUrl, uses Http RpcApiHost. */
     runToken?: string;
@@ -23,13 +23,13 @@ export type SourceComputeHostOptions = {
 };
 export interface SourceComputeHost extends ComputeHost {
 }
+/** Company `events` handlers, by event name. */
+export declare function eventsToFuncMap(events: AnyEventHandlers | undefined): FuncMap;
 /**
  * Local host: call author FuncMap implementations directly (no SequenceBuild.code).
  *
- * Lookup by name, then dispatch on `kind`:
- * - caseContextView: `args[0]` is the raw snapshot (identity when no view).
- * - compute / boolCompute / custom: `args[0]` is the raw snapshot (projected internally).
- * - system: `args[0]` is the params object.
+ * Lookup by name, then `fn(ctx, args)` (38 §2.1): the Orchestrator gets its own ctx (with `api.tools`),
+ * every other function a function's.
  */
 export declare function createSourceComputeHost(options: SourceComputeHostOptions): SourceComputeHost;
 //# sourceMappingURL=source-compute-host.d.ts.map

package/dist/compute-host/source-compute-host.js

@@ -1,63 +1,56 @@
-import { resolveCaseContextViewFn } from '../core/functions/define/case-context.js';
-import { buildActionContext } from '../fn-context/build-context.js';
-import { resolveSystemFnParams } from '../fn-context/system-args.js';
+import { isSystemEventName } from '../core/functions/events.js';
+import { ORCHESTRATOR_FUNCTION } from '../core/case-orchestrator/types.js';
+import { buildActionContext, buildCaseOrchestratorContext } from '../fn-context/build-context.js';
+import { resolveFnParams } from '../fn-context/fn-params.js';
 import { createFakeApiHost } from '../fn-context/fake/index.js';
 import { createRpcApiHost } from '../fn-context/rpc/index.js';
-import { makeCtx } from '../fn-context/make-ctx.js';
-function requireSlots(name, args) {
-    const slots = args[0];
-    if (slots == null) {
-        throw new Error(`Function ${name}: args[0] (slots) required`);
+import { makeCaseOrchestratorCtx, makeCtx } from '../fn-context/make-ctx.js';
+import { getLogger } from '../logger.js';
+const logger = getLogger(['runtime', 'source']);
+/** Company `events` handlers, by event name. */
+export function eventsToFuncMap(events) {
+    const out = {};
+    for (const [name, handler] of Object.entries(events ?? {})) {
+        if (isSystemEventName(name) && typeof handler === 'function')
+            out[name] = handler;
     }
-    return slots;
+    return out;
 }
 /**
  * Local host: call author FuncMap implementations directly (no SequenceBuild.code).
  *
- * Lookup by name, then dispatch on `kind`:
- * - caseContextView: `args[0]` is the raw snapshot (identity when no view).
- * - compute / boolCompute / custom: `args[0]` is the raw snapshot (projected internally).
- * - system: `args[0]` is the params object.
+ * Lookup by name, then `fn(ctx, args)` (38 §2.1): the Orchestrator gets its own ctx (with `api.tools`),
+ * every other function a function's.
  */
 export function createSourceComputeHost(options) {
     const { functions, data } = options;
-    if (Object.hasOwn(functions, 'caseContextView')) {
-        throw new Error(`functions map already has 'caseContextView'; that name is the sequence view`);
+    const eventFns = eventsToFuncMap(options.events);
+    for (const name of Object.keys(eventFns)) {
+        if (Object.hasOwn(functions, name)) {
+            throw new Error(`functions and events must not share names: ${name}`);
+        }
     }
     const apiHost = resolveApiHost(options);
-    const viewFn = resolveCaseContextViewFn(options.caseContextView) ?? ((slots) => slots);
-    const registry = {
-        ...functions,
-        caseContextView: { kind: 'caseContextView', main: viewFn },
-    };
+    const registry = { ...functions, ...eventFns };
     async function systemContext() {
         return data ? buildActionContext(data, apiHost) : makeCtx();
     }
+    async function caseOrchestratorContext() {
+        return data ? buildCaseOrchestratorContext(data, apiHost) : makeCaseOrchestratorCtx();
+    }
     return {
-        async execute(name, args = []) {
-            const def = registry[name];
-            if (!def) {
+        async execute(name, invocation = {}) {
+            const fn = registry[name];
+            if (!fn) {
                 throw new Error(`Missing function: ${name}`);
             }
-            if (def.kind === 'caseContextView') {
-                return def.main(requireSlots(name, args));
-            }
-            if (def.kind === 'compute' || def.kind === 'boolCompute') {
-                return def.main(viewFn(requireSlots(name, args)));
-            }
-            if (def.kind === 'custom') {
-                const caseContext = viewFn(requireSlots(name, args));
-                const ctx = await systemContext();
-                const fn = def.main;
-                return fn(caseContext, { ...ctx, params: args[1] ?? {} });
-            }
-            const params = resolveSystemFnParams(args);
+            const args = resolveFnParams(invocation.args);
             const contextStarted = Date.now();
-            const ctx = await systemContext();
-            console.log(`[source timing] ${name} context ${Date.now() - contextStarted}ms`);
+            const ctx = name === ORCHESTRATOR_FUNCTION ? await caseOrchestratorContext() : await systemContext();
+            logger.info('context built', { name, durationMs: Date.now() - contextStarted });
             const functionStarted = Date.now();
-            const result = await def.main({ ...ctx, params });
-            console.log(`[source timing] ${name} function ${Date.now() - functionStarted}ms`);
+            const result = await fn(ctx, args);
+            logger.info('function executed', { name, durationMs: Date.now() - functionStarted });
             return result;
         },
         dispose() { },

package/dist/core/case-orchestrator/contact-hours.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Contact hours in company code (25 §3): when a company may reach a contact on its own. The platform
+ * does not check them; the company writes its rules (by topic, state, channel) in the repository and
+ * books `at` with these helpers. Pure calendar math in the contact's local time, with no legal content
+ * (no built-in quiet hours). Part of the company API (`src/index.ts`), bundled into
+ * company code as is: no imports.
+ */
+export type ContactHoursWeekday = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+/** A local time range, `HH:MM` to `HH:MM` (`24:00` ends at midnight), start before end. */
+export type ContactHoursRange = {
+    start: string;
+    end: string;
+};
+/** `OfficeHours` without `timezone`: always read in the contact's own zone. */
+export type ContactHours = {
+    week: Record<ContactHoursWeekday, ContactHoursRange[]>;
+    /** Recurring dates (`MM-DD`) whose hours replace `week`; `[]` means no contact that day. */
+    holidays?: {
+        date: string;
+        hours: ContactHoursRange[];
+    }[];
+    /** One-off dates (`YYYY-MM-DD`) whose hours replace `holidays` and `week`. */
+    overrides?: {
+        date: string;
+        hours: ContactHoursRange[];
+    }[];
+    /**
+     * Whose hours: left out, the company's contact-hours rules; `contact_schedule`, a contact's own
+     * (`contactScheduleHours`); `cadence`, the code's own pacing (one call a day: today closed once it had
+     * its call), which holds whatever an environment being tested lets go (`ctx.time.ignore`).
+     */
+    source?: 'contact_schedule' | 'cadence';
+};
+/** What does not hold while the environment is tested (`ctx.time.ignore`, 68 §6.2). */
+export type ContactHoursIgnore = Readonly<{
+    contactHours: boolean;
+    contactSchedule: boolean;
+}>;
+/** The contact's own `contact_schedule` value (when they said they may be reached). */
+export type ContactScheduleValue = {
+    weekly: Record<ContactHoursWeekday, ContactHoursRange[]> | null;
+    dateOverrides: {
+        dates: string[];
+        windows: ContactHoursRange[];
+    }[];
+};
+/** Every day of the week with the same hours. */
+export declare function everyDay(hours: ContactHoursRange[]): Record<ContactHoursWeekday, ContactHoursRange[]>;
+/** A contact's `contact_schedule` as contact hours (no schedule: any time), to intersect with the company's. */
+export declare function contactScheduleHours(schedule: ContactScheduleValue | null | undefined): ContactHours;
+/** The hours on a local date (`YYYY-MM-DD`): an override, else a holiday, else the weekday. */
+export declare function contactHoursOn(hours: ContactHours, day: string): ContactHoursRange[];
+/**
+ * Whether `at` (a Date, ISO string or epoch ms) falls inside `hours` (one, or a list that must all allow it)
+ * in `timezone`. `ignore` (`ctx.time.ignore`): what does not hold while the environment is tested; when
+ * nothing is left to hold, any time is.
+ */
+export declare function withinContactHours(hours: ContactHours | readonly ContactHours[], at: Date | string | number, timezone: string, ignore?: ContactHoursIgnore): boolean;
+/**
+ * The first time at or after `from` inside `hours` (one, or a list that must all allow it: the company's
+ * rules and the contact's own schedule), in `timezone`, as an ISO string for `at`; null when there is none
+ * within `days` (default 14). `from` is `ctx.time` (its `now`, and what does not hold while the environment
+ * is tested: `ctx.time.ignore`, 68 §6.2), or a Date, ISO string or epoch ms. When nothing is left to hold,
+ * `from` itself.
+ */
+export declare function nextContactTime(hours: ContactHours | readonly ContactHours[], from: Date | string | number | {
+    now: number;
+    ignore?: ContactHoursIgnore;
+}, timezone: string, days?: number): string | null;
+//# sourceMappingURL=contact-hours.d.ts.map

package/dist/core/case-orchestrator/contact-hours.js

@@ -0,0 +1,127 @@
+/**
+ * Contact hours in company code (25 §3): when a company may reach a contact on its own. The platform
+ * does not check them; the company writes its rules (by topic, state, channel) in the repository and
+ * books `at` with these helpers. Pure calendar math in the contact's local time, with no legal content
+ * (no built-in quiet hours). Part of the company API (`src/index.ts`), bundled into
+ * company code as is: no imports.
+ */
+const WEEKDAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+const ALL_DAY = [{ start: '00:00', end: '24:00' }];
+const DAY_MS = 86_400_000;
+/** Every day of the week with the same hours. */
+export function everyDay(hours) {
+    return { mon: hours, tue: hours, wed: hours, thu: hours, fri: hours, sat: hours, sun: hours };
+}
+/** A contact's `contact_schedule` as contact hours (no schedule: any time), to intersect with the company's. */
+export function contactScheduleHours(schedule) {
+    return {
+        week: schedule?.weekly ?? everyDay(ALL_DAY),
+        overrides: (schedule?.dateOverrides ?? []).flatMap((override) => override.dates.map((date) => ({ date, hours: override.windows }))),
+        source: 'contact_schedule',
+    };
+}
+/** `hours` without what `ignore` lets go: the company's rules, the contact's own schedule; never a cadence. */
+function held(hours, ignore) {
+    if (!ignore)
+        return hours;
+    return hours.filter((entry) => entry.source === 'cadence' ? true : entry.source === 'contact_schedule' ? !ignore.contactSchedule : !ignore.contactHours);
+}
+/** The hours on a local date (`YYYY-MM-DD`): an override, else a holiday, else the weekday. */
+export function contactHoursOn(hours, day) {
+    const override = hours.overrides?.find((entry) => entry.date === day);
+    if (override)
+        return override.hours;
+    const holiday = hours.holidays?.find((entry) => entry.date === day.slice(5));
+    if (holiday)
+        return holiday.hours;
+    return hours.week[WEEKDAYS[new Date(`${day}T12:00:00Z`).getUTCDay()]] ?? [];
+}
+function minutes(time) {
+    const match = /^(\d{2}):(\d{2})$/.exec(time);
+    if (!match)
+        throw new Error(`contact hours: "${time}" is not HH:MM`);
+    return Number(match[1]) * 60 + Number(match[2]);
+}
+function clock(total) {
+    return `${String(Math.floor(total / 60)).padStart(2, '0')}:${String(total % 60).padStart(2, '0')}`;
+}
+/** Where two lists of ranges overlap. */
+function intersect(a, b) {
+    const out = [];
+    for (const x of a) {
+        for (const y of b) {
+            const start = Math.max(minutes(x.start), minutes(y.start));
+            const end = Math.min(minutes(x.end), minutes(y.end));
+            if (start < end)
+                out.push({ start: clock(start), end: clock(end) });
+        }
+    }
+    return out.sort((p, q) => minutes(p.start) - minutes(q.start));
+}
+/** The ranges on a local date that every one of `all` allows. */
+function rangesOn(all, day) {
+    return all.reduce((ranges, hours) => intersect(ranges, contactHoursOn(hours, day)), ALL_DAY);
+}
+function localParts(at, timezone) {
+    const parts = Object.fromEntries(new Intl.DateTimeFormat('en-US', { timeZone: timezone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' })
+        .formatToParts(at)
+        .map((part) => [part.type, part.value]));
+    return { day: `${parts.year}-${parts.month}-${parts.day}`, minute: Number(parts.hour) * 60 + Number(parts.minute) };
+}
+/** The UTC instant of a local wall time (two passes, right on DST days). */
+function instantOf(day, minute, timezone) {
+    const wall = Date.parse(`${day}T00:00:00Z`) + minute * 60_000;
+    let guess = wall;
+    for (let pass = 0; pass < 2; pass += 1) {
+        const seen = localParts(new Date(guess), timezone);
+        const seenWall = Date.parse(`${seen.day}T00:00:00Z`) + seen.minute * 60_000;
+        guess += wall - seenWall;
+    }
+    return guess;
+}
+function addDays(day, count) {
+    return new Date(Date.parse(`${day}T00:00:00Z`) + count * DAY_MS).toISOString().slice(0, 10);
+}
+function list(hours) {
+    return Array.isArray(hours) ? hours : [hours];
+}
+/**
+ * Whether `at` (a Date, ISO string or epoch ms) falls inside `hours` (one, or a list that must all allow it)
+ * in `timezone`. `ignore` (`ctx.time.ignore`): what does not hold while the environment is tested; when
+ * nothing is left to hold, any time is.
+ */
+export function withinContactHours(hours, at, timezone, ignore) {
+    const kept = held(list(hours), ignore);
+    if (kept.length === 0)
+        return true;
+    const local = localParts(new Date(at), timezone);
+    return rangesOn(kept, local.day).some((range) => local.minute >= minutes(range.start) && local.minute < minutes(range.end));
+}
+/**
+ * The first time at or after `from` inside `hours` (one, or a list that must all allow it: the company's
+ * rules and the contact's own schedule), in `timezone`, as an ISO string for `at`; null when there is none
+ * within `days` (default 14). `from` is `ctx.time` (its `now`, and what does not hold while the environment
+ * is tested: `ctx.time.ignore`, 68 §6.2), or a Date, ISO string or epoch ms. When nothing is left to hold,
+ * `from` itself.
+ */
+export function nextContactTime(hours, from, timezone, days = 14) {
+    const time = typeof from === 'object' && !(from instanceof Date) ? from : null;
+    const start = new Date(time ? time.now : from).getTime();
+    if (!Number.isFinite(start))
+        throw new Error('nextContactTime: from must be a time');
+    const all = held(list(hours), time?.ignore);
+    if (all.length === 0)
+        return new Date(start).toISOString();
+    const today = localParts(new Date(start), timezone).day;
+    for (let offset = 0; offset <= days; offset += 1) {
+        const day = addDays(today, offset);
+        for (const range of rangesOn(all, day)) {
+            const end = instantOf(day, minutes(range.end), timezone);
+            if (end <= start)
+                continue;
+            return new Date(Math.max(start, instantOf(day, minutes(range.start), timezone))).toISOString();
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=contact-hours.js.map

package/dist/core/case-orchestrator/index.d.ts

@@ -0,0 +1,3 @@
+export { ACTIVITY_RECENT_LIMIT, ORCHESTRATOR_ENTRY, ORCHESTRATOR_FUNCTION, CASE_ORCHESTRATOR_TOOL_NAMES, EMPTY_CASE_ACTIVITY, RECENT_AGREED_ACTIONS_DAYS, type ActivityStats, type AgreementFields, type CaseActivity, type CaseOrchestrator, type CaseOrchestratorApi, type CaseOrchestratorArgs, type CaseOrchestratorContext, type CaseOrchestratorManifest, type CaseOrchestratorParams, type CaseOrchestratorToolName, type CaseOrchestratorTools, type ChannelAvailability, type ChannelUnavailableReason, type ExchangeEntry, type ExchangeEvent, type ExchangeSearchHit, type ContactActionInput, type ContactActionView, type ContactChannel, type PartyContactHours, type FinishedAgreedActionView, type PartyActivity, type ReadExchangeResult, type RescheduledResult, type RunTrigger, type RunTriggerType, type ScheduleUpdateSlotsInput, type SlotFieldWriteInput, type SlotInsertInput, type SlotWriteInput, type ScheduleTiming, type ScheduledActionInput, type ScheduledActionInputs, type ScheduledActionKind, type ScheduledActionTiming, type ScheduledActionView, type SearchExchangesResult, type ToolCallArgs, type ToolCallResult, type ToolResult, type UpdateSlotsActionInput, type UpdateSlotsActionView, type ScheduleWakeInput, type WakeActionInput, type WakeActionView, type WakeResult, } from './types.js';
+export { localDateTime, localDay, render, zonedIso, type ConversationOptions, type TimelineOptions } from './render.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/case-orchestrator/index.js

@@ -0,0 +1,3 @@
+export { ACTIVITY_RECENT_LIMIT, ORCHESTRATOR_ENTRY, ORCHESTRATOR_FUNCTION, CASE_ORCHESTRATOR_TOOL_NAMES, EMPTY_CASE_ACTIVITY, RECENT_AGREED_ACTIONS_DAYS, } from './types.js';
+export { localDateTime, localDay, render, zonedIso } from './render.js';
+//# sourceMappingURL=index.js.map

package/dist/core/case-orchestrator/render.d.ts

@@ -0,0 +1,75 @@
+import type { CaseActivity, ChannelAvailability, FinishedAgreedActionView, PartyActivity, ReadExchangeResult, RunTrigger, ScheduledActionView } from './types.js';
+/** `YYYY-MM-DD` of an instant in `timezone`. */
+export declare function localDay(at: string | Date, timezone: string): string;
+/** `YYYY-MM-DD HH:mm:ss` of an instant in `timezone`. */
+export declare function localDateTime(at: string | Date, timezone: string): string;
+/** ISO 8601 in `timezone` with its UTC offset, e.g. `2026-10-09T06:25:00-04:00`: a time that names its own zone. */
+export declare function zonedIso(at: string | Date, timezone: string): string;
+/** `Current local time: 2026-10-08 10:05:00, Thursday, and October has 31 days`. */
+declare function renderLocalClock(now: Date, timezone: string): string;
+/** One party: `Today is [day 3]` and today's counts. */
+declare function partyActivitySummary(party: PartyActivity): string;
+/** The whole case: the Case day and today's counts. */
+declare function caseActivitySummary(activity: CaseActivity): string;
+/**
+ * The party's own contact hours (their `contact_schedule`), in their timezone: a line per weekday
+ * (`every day` when all are the same), then one per date that differs. None on file: one line saying
+ * so. The company's rules for when to reach them are its own (25 §3), not shown here.
+ */
+declare function partyContactHours(party: Pick<PartyActivity, 'contactHours'>): string;
+/** `sms: true` per channel; an unavailable one says why. */
+declare function partyChannelAvailability(availability: ChannelAvailability): string;
+export type TimelineOptions = {
+    /** Only the last `sinceDays` days (today counts as one). */
+    sinceDays?: number;
+    /** At most this many of the newest events. */
+    limit?: number;
+};
+/** Events grouped by day: `[day N] [YYYY-MM-DD]:`, then `[YYYY-MM-DD HH:mm:ss] <event> exchangeId …`. */
+declare function partyTimeline(party: PartyActivity, options?: TimelineOptions): string;
+/**
+ * `- <id>: <kind> at <local time> [agreed in …] (<note or reason>) {"timing":…}`; an agreed
+ * follow-up is marked, scheduled slot writes say why and carry their `writes`, a hand-over names its
+ * sequence, a wake-up its name. `(none)` when empty.
+ */
+declare function pendingActions(actions: readonly ScheduledActionView[], timezone: string): string;
+/**
+ * Why the Run woke up when nothing happened in a conversation (25 §6): each `timer` (a wake-up the
+ * Orchestrator booked) and `external` trigger (company code's `instances.notify`), as
+ * `- timer <name> at <local time> (<note>)` / `- external <reason> at <local time>`.
+ * `(none)` when there are none.
+ */
+declare function wakeUps(triggers: readonly RunTrigger[], timezone: string): string;
+/**
+ * Finished agreed follow-ups: `- <id>: <kind> at <local time> [agreed in …], <status> at <local time> (<note>)`,
+ * the second time being when it finished. `(none)` when empty.
+ */
+declare function recentAgreedActions(actions: readonly FinishedAgreedActionView[], timezone: string): string;
+export type ConversationOptions = {
+    /** Only the newest `limit` entries. */
+    limit?: number;
+};
+/**
+ * One exchange's words (a `readExchange` result): a head line naming it, then
+ * `[YYYY-MM-DD HH:mm:ss] customer|rep: <text>` per entry, in `timezone`.
+ */
+declare function conversation(result: ReadExchangeResult, timezone: string, options?: ConversationOptions): string;
+/**
+ * Text for company code to show or log (docs/design/08-case-orchestrator.md §5.3), in the mars next-step
+ * format. Party functions take one contact's activity (`activity.byContact[contactId]`) and
+ * write its local wall-clock times.
+ */
+export declare const render: {
+    localClock: typeof renderLocalClock;
+    activitySummary: typeof partyActivitySummary;
+    caseActivitySummary: typeof caseActivitySummary;
+    contactHours: typeof partyContactHours;
+    channelAvailability: typeof partyChannelAvailability;
+    timeline: typeof partyTimeline;
+    pendingActions: typeof pendingActions;
+    recentAgreedActions: typeof recentAgreedActions;
+    wakeUps: typeof wakeUps;
+    conversation: typeof conversation;
+};
+export {};
+//# sourceMappingURL=render.d.ts.map