@superpanel-sdk/runtime 0.2.3 → 0.5.0

package/dist/cli/type-gen/index.js

@@ -1,11 +1,16 @@
 import path from 'node:path';
 import chokidar from 'chokidar';
-import { checkAll, generateAll, generateSequence, listSequenceIds } from '../../builder/codegen/generate.js';
-async function runOnce(repoRoot) {
-    const results = await generateAll(repoRoot);
+import { checkAll, companyGenPaths, generateAll, listSequenceIds } from '../../builder/codegen/generate.js';
+async function runOnce(repoRoot, sequenceIds) {
+    const results = await generateAll(repoRoot, { sequenceIds });
+    if (!sequenceIds) {
+        for (const outPath of Object.values(companyGenPaths(repoRoot)))
+            console.log(`wrote ${path.relative(repoRoot, outPath)}`);
+    }
     for (const result of results) {
         console.log(`wrote ${path.relative(repoRoot, result.outPath)}`);
         console.log(`wrote ${path.relative(repoRoot, result.caseContextOutPath)}`);
+        console.log(`wrote ${path.relative(repoRoot, result.indexOutPath)}`);
     }
 }
 /** `sequences/<id>/…` → sequence id */
@@ -36,11 +41,7 @@ async function runWatch(repoRoot) {
                     await runOnce(repoRoot);
                     return;
                 }
-                for (const sequenceId of job.sequences) {
-                    const result = await generateSequence(repoRoot, sequenceId);
-                    console.log(`wrote ${path.relative(repoRoot, result.outPath)}`);
-                    console.log(`wrote ${path.relative(repoRoot, result.caseContextOutPath)}`);
-                }
+                await runOnce(repoRoot, [...job.sequences]);
             }
             catch (error) {
                 console.error('[type:gen] regenerate failed:', error instanceof Error ? error.message : error);

package/dist/compiler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * What the platform's compile child loads from the runtime the company repo installed
+ * (`packages/services/src/release/compile-child.ts`). Platform-only: the package resolves
+ * `./compiler` under the `superpanel-platform` condition, and the child loads it by file path.
+ */
+export { compileRepo, type CompileRepoEvent, type CompileRepoOptions, type CompileRepoSequenceResult, } from './builder/compile/compile-sequence.js';
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.js

@@ -0,0 +1,7 @@
+/**
+ * What the platform's compile child loads from the runtime the company repo installed
+ * (`packages/services/src/release/compile-child.ts`). Platform-only: the package resolves
+ * `./compiler` under the `superpanel-platform` condition, and the child loads it by file path.
+ */
+export { compileRepo, } from './builder/compile/compile-sequence.js';
+//# sourceMappingURL=compiler.js.map

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

@@ -1,38 +1,30 @@
-import type { CaseContextViewFn } from '../core/functions/define/case-context.js';
-import type { RuntimeSlotsSnapshot } from '../core/slot/types.js';
 /**
- * Pluggable host for sequence functions (derived / finishWhen / custom / system).
+ * Pluggable host for sequence functions (case / noCase / orchestrator functions).
  *
  * - Local unit tests / company CI: {@link createLocalComputeHost} (direct JS call)
  * - Author FuncMap: `createSourceComputeHost`
  * - Platform backend: QuickJS / Cloudflare Worker hosts with the same `execute` surface
  */
 export interface ComputeHost {
-    /**
-     * Invoke a registered function by name, then dispatch on `kind`.
-     * Compute/boolCompute/custom: `args[0]` is the raw snapshot (projected internally).
-     * `caseContextView`: `args[0]` is the raw snapshot (identity when the sequence has no view).
-     */
-    execute(name: string, args?: unknown[]): Promise<unknown>;
+    /** Invoke a registered function with its type-specific invocation. */
+    execute(name: string, invocation?: ComputeInvocation): Promise<unknown>;
     /** Release host-owned resources. No-op when the host has nothing to free. */
     dispose(): void;
 }
+/** Input for case, noCase and orchestrator functions. */
+export type FunctionInvocation = {
+    caseContext?: unknown;
+    params?: object;
+};
+export type ComputeInvocation = FunctionInvocation;
+export declare function parseComputeInvocation(value: unknown): ComputeInvocation | null;
 /**
- * Name → computeFn. Parameter typed as `never` so company-narrowed
- * `ComputeFn<CaseContext>` maps remain assignable (TS contravariance).
+ * Name → plain function of `caseContext` (local tests stand in sequence functions with these).
+ * Parameter typed as `never` so company-narrowed maps remain assignable (TS contravariance).
  */
-export type ComputeFnMap = Record<string, (slots: never) => unknown | Promise<unknown>>;
+export type ComputeFnMap = Record<string, (caseContext: never) => unknown | Promise<unknown>>;
 export type ComputeHostOrFns = ComputeHost | ComputeFnMap;
-export type LocalComputeHostOptions = {
-    /**
-     * Optional `(slots) => CaseContext` projector. Registered under the view.ts
-     * export name `caseContextView` and invoked before each compute fn
-     * (no cross-call cache — snapshot may change mid-recompute).
-     */
-    caseContextView?: CaseContextViewFn<RuntimeSlotsSnapshot, unknown>;
-};
-/** In-process host: call plain JS computeFns. No VM, no I/O fence. */
-export declare function createLocalComputeHost(fns: ComputeFnMap, options?: LocalComputeHostOptions): ComputeHost;
+export declare function createLocalComputeHost(fns: ComputeFnMap): ComputeHost;
 /** Accept either a host or a name→fn map (map is wrapped as local host). */
-export declare function resolveComputeHost(hostOrFns: ComputeHostOrFns, options?: LocalComputeHostOptions): ComputeHost;
+export declare function resolveComputeHost(hostOrFns: ComputeHostOrFns): ComputeHost;
 //# sourceMappingURL=compute-host.d.ts.map

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

@@ -1,45 +1,42 @@
+export function parseComputeInvocation(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.params !== undefined &&
+        (typeof record.params !== 'object' || record.params === null || Array.isArray(record.params))) {
+        return null;
+    }
+    return {
+        ...(Object.hasOwn(record, 'caseContext') ? { caseContext: record.caseContext } : {}),
+        ...(record.params !== undefined ? { params: record.params } : {}),
+    };
+}
 function isComputeHost(value) {
     return typeof value.execute === 'function';
 }
-function requireSlots(name, args) {
-    const slots = args[0];
-    if (slots == null) {
-        throw new Error(`Function ${name}: args[0] (slots) required`);
+function requireCaseContext(name, invocation) {
+    if (!Object.hasOwn(invocation, 'caseContext')) {
+        throw new Error(`Function ${name}: caseContext required`);
     }
-    return slots;
+    return invocation.caseContext;
 }
-/** In-process host: call plain JS computeFns. No VM, no I/O fence. */
-export function createLocalComputeHost(fns, options = {}) {
-    if (Object.hasOwn(fns, 'caseContextView')) {
-        throw new Error(`computeFn name 'caseContextView' collides with the sequence view`);
-    }
-    const viewFn = options.caseContextView ?? ((slots) => slots);
-    const registry = {
-        caseContextView: { kind: 'caseContextView', main: viewFn },
-    };
-    for (const [name, fn] of Object.entries(fns)) {
-        registry[name] = { kind: 'compute', main: fn };
-    }
+export function createLocalComputeHost(fns) {
     return {
-        async execute(name, args = []) {
-            const def = registry[name];
-            if (!def) {
-                throw new Error(`Missing computeFn implementation: ${name}`);
-            }
-            const snapshot = requireSlots(name, args);
-            if (def.kind === 'caseContextView') {
-                return def.main(snapshot);
+        async execute(name, invocation = {}) {
+            const fn = fns[name];
+            if (!fn) {
+                throw new Error(`Missing function implementation: ${name}`);
             }
-            return def.main(viewFn(snapshot));
+            return fn(requireCaseContext(name, invocation));
         },
         dispose() { },
     };
 }
 /** Accept either a host or a name→fn map (map is wrapped as local host). */
-export function resolveComputeHost(hostOrFns, options) {
+export function resolveComputeHost(hostOrFns) {
     if (isComputeHost(hostOrFns)) {
         return hostOrFns;
     }
-    return createLocalComputeHost(hostOrFns, options);
+    return createLocalComputeHost(hostOrFns);
 }
 //# sourceMappingURL=compute-host.js.map

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

@@ -1,7 +1,5 @@
-export { createLocalComputeHost, resolveComputeHost } from './compute-host.js';
-export type { ComputeFnMap, ComputeHost, ComputeHostOrFns, LocalComputeHostOptions } from './compute-host.js';
+export { createLocalComputeHost, parseComputeInvocation, resolveComputeHost } from './compute-host.js';
+export type { ComputeFnMap, ComputeHost, ComputeHostOrFns, ComputeInvocation, FunctionInvocation, } from './compute-host.js';
 export { createSourceComputeHost } from './source-compute-host.js';
 export type { SourceComputeHost, SourceComputeHostOptions } from './source-compute-host.js';
-export { readOnlyComputeNames, withReadOnlyComputeCache } from './read-only-cache.js';
-export type { ReadOnlyComputeCacheOptions } from './read-only-cache.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/compute-host/index.js

@@ -1,4 +1,3 @@
-export { createLocalComputeHost, resolveComputeHost } from './compute-host.js';
+export { createLocalComputeHost, parseComputeInvocation, resolveComputeHost } from './compute-host.js';
 export { createSourceComputeHost } from './source-compute-host.js';
-export { readOnlyComputeNames, withReadOnlyComputeCache } from './read-only-cache.js';
 //# sourceMappingURL=index.js.map

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 with the table-fixed kind. */
+    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 ctx for case / noCase / orchestrator. */
     data?: ActionDataSlice;
     /** When set with data.config.backendUrl, uses Http RpcApiHost. */
     runToken?: string;
@@ -23,13 +23,15 @@ export type SourceComputeHostOptions = {
 };
 export interface SourceComputeHost extends ComputeHost {
 }
+/** Company `events` handlers as DefinedFunc entries (kind from the platform event table). */
+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.
+ * - case: `fn(caseContext, { ...ctx, params })`; caseContext required.
+ * - orchestrator: same, with the Case Orchestrator ctx.
+ * - noCase: `fn({ ...ctx, params })`; caseContext must be absent.
  */
 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,77 @@
-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, systemEventKind } from '../core/functions/events.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']);
+function requireCaseContext(name, invocation) {
+    if (!Object.hasOwn(invocation, 'caseContext'))
+        throw new Error(`Function ${name}: caseContext required`);
+    return invocation.caseContext;
+}
+/** Company `events` handlers as DefinedFunc entries (kind from the platform event table). */
+export function eventsToFuncMap(events) {
+    const out = {};
+    for (const [name, handler] of Object.entries(events ?? {})) {
+        if (!isSystemEventName(name) || typeof handler !== 'function')
+            continue;
+        out[name] = { kind: systemEventKind(name), main: 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.
+ * - case: `fn(caseContext, { ...ctx, params })`; caseContext required.
+ * - orchestrator: same, with the Case Orchestrator ctx.
+ * - noCase: `fn({ ...ctx, params })`; caseContext must be absent.
  */
 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 = []) {
+        async execute(name, invocation = {}) {
             const def = registry[name];
             if (!def) {
                 throw new Error(`Missing function: ${name}`);
             }
-            if (def.kind === 'caseContextView') {
-                return def.main(requireSlots(name, args));
+            const functionInvocation = invocation;
+            const params = resolveFnParams(functionInvocation.params);
+            if (def.kind === 'case') {
+                const caseContext = requireCaseContext(name, functionInvocation);
+                const ctx = await systemContext();
+                return def.main(caseContext, { ...ctx, params });
             }
-            if (def.kind === 'compute' || def.kind === 'boolCompute') {
-                return def.main(viewFn(requireSlots(name, args)));
+            if (def.kind === 'orchestrator') {
+                const caseContext = requireCaseContext(name, functionInvocation);
+                const ctx = await caseOrchestratorContext();
+                return def.main(caseContext, { ...ctx, params: params });
             }
-            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] ?? {} });
+            if (Object.hasOwn(functionInvocation, 'caseContext')) {
+                throw new Error(`Function ${name}: noCase function must not receive caseContext`);
             }
-            const params = resolveSystemFnParams(args);
             const contextStarted = Date.now();
             const ctx = await systemContext();
-            console.log(`[source timing] ${name} context ${Date.now() - contextStarted}ms`);
+            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`);
+            logger.info('function executed', { name, durationMs: Date.now() - functionStarted });
             return result;
         },
         dispose() { },

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

@@ -0,0 +1,50 @@
+/**
+ * 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[];
+    }[];
+};
+/** 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`. */
+export declare function withinContactHours(hours: ContactHours | readonly ContactHours[], at: Date | string | number, timezone: string): boolean;
+/**
+ * The first time at or after `from` (a Date, ISO string or epoch ms, e.g. `ctx.time.now`) 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).
+ */
+export declare function nextContactTime(hours: ContactHours | readonly ContactHours[], from: Date | string | number, timezone: string, days?: number): string | null;
+//# sourceMappingURL=contact-hours.d.ts.map

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

@@ -0,0 +1,108 @@
+/**
+ * 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 }))),
+    };
+}
+/** 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`. */
+export function withinContactHours(hours, at, timezone) {
+    const local = localParts(new Date(at), timezone);
+    return rangesOn(list(hours), local.day).some((range) => local.minute >= minutes(range.start) && local.minute < minutes(range.end));
+}
+/**
+ * The first time at or after `from` (a Date, ISO string or epoch ms, e.g. `ctx.time.now`) 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).
+ */
+export function nextContactTime(hours, from, timezone, days = 14) {
+    const start = new Date(from).getTime();
+    if (!Number.isFinite(start))
+        throw new Error('nextContactTime: from must be a time');
+    const all = list(hours);
+    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/follow-ups.d.ts

@@ -0,0 +1,31 @@
+import { type CaseOrchestratorParams, type CaseOrchestratorTools, type ReadExchangeResult } from './types.js';
+type ConversationReadContext = {
+    params: Pick<CaseOrchestratorParams, 'triggers'>;
+    api: {
+        tools: Pick<CaseOrchestratorTools, 'readExchange'>;
+    };
+};
+/**
+ * The conversations that started this Run (a connected call, an SMS or email turn), read with
+ * `readExchange`: a whole call, the last {@link THREAD_MESSAGES_SHOWN} messages of a thread.
+ * A read that fails is left out.
+ */
+declare function readTriggeringConversations(ctx: ConversationReadContext): Promise<ReadExchangeResult[]>;
+/**
+ * One customer's follow-up block, in their local time: `New conversations:` (only when this
+ * customer has one: a whole call, the last messages of a thread), `Pending scheduled actions:` and
+ * `Finished agreed follow-ups (last N days):`.
+ */
+declare function customerSection(params: Pick<CaseOrchestratorParams, 'activity' | 'scheduledActions' | 'recentAgreedActions'>, contactId: string, conversations: readonly ReadExchangeResult[]): string;
+/**
+ * The rules after the company's own: applying day-N rules and keeping agreed follow-ups, every Run;
+ * booking agreed follow-ups too when the Run read a conversation.
+ */
+declare function rules(conversations: readonly ReadExchangeResult[]): string;
+export declare const followUps: {
+    readTriggeringConversations: typeof readTriggeringConversations;
+    customerSection: typeof customerSection;
+    rules: typeof rules;
+};
+export {};
+//# sourceMappingURL=follow-ups.d.ts.map

package/dist/core/case-orchestrator/follow-ups.js

@@ -0,0 +1,103 @@
+// Bundled into company code as is (part of the company API, `src/index.ts`), so it imports render and types only.
+import { render } from './render.js';
+import { RECENT_AGREED_ACTIONS_DAYS, } from './types.js';
+/**
+ * Follow-ups in a company prompt, in the mars next-step format (docs/design/08-case-orchestrator.md
+ * §5.3, docs/design/09-agreed-follow-up.md): how to apply day-N rules on this platform, read what
+ * was just said, each customer's follow-ups, and the rules for booking and keeping agreed ones. The
+ * rules name what the platform computes and writes (`Today is [day N]` from
+ * `render.activitySummary`, the headings and marks here, the schedule tools), so use them together.
+ */
+/** SMS and email threads are long: the last messages are enough to see what was just agreed. */
+const THREAD_MESSAGES_SHOWN = 10;
+/** Regular follow-ups: applying the company's day-N rules with the schedule tools. */
+const DAY_RULES = `How to apply the rules (day N is the Nth day since the first interaction with that customer):
+- Find each customer's current day ("Today is [day N]") and apply that day's rule. Rules for past days no longer apply.
+- The next follow-up is what we do if the customer stops responding from now on. Every customer always has their next follow-up scheduled; if a pending one still fits the rules, leave it.
+- If today's rule is already done or needs nothing, look ahead to the first later day whose rule needs doing.
+- Give at, the exact time it runs: the time a rule names (e.g. 5 minutes after a call), or for a day rule a time that day inside the hours the company's rules allow and the customer's own hours if shown. It runs then; nothing moves it.
+- Use only an available channel.
+- If no later rule needs doing, schedule nothing.`;
+const AGREED_RULES = `Agreed follow-ups:
+- Pending actions marked [agreed …] were promised. Keep them. Change or cancel one only if the customer changed or withdrew it, and give the reason.
+- Do not schedule a regular follow-up before an agreed one on the same day.
+- If an agreed follow-up failed or was not answered, continue with the day rules.`;
+const BOOKING_RULES = `Booking agreed follow-ups:
+- "New conversations" shows what was just said. If the customer asked us to call, text or email them at a time, or agreed to a time we offered, book it as an agreed follow-up: the schedule tool with agreedInExchangeId, agreedAt (the time of the customer's message saying it, copied from its [time], with the customer's offset), customerQuote (their exact words) and note. Give at, the exact time it runs; for a vague one ("tomorrow afternoon"), pick a time inside what they said and inside the hours the company's rules allow. Resolve relative times ("in 10 minutes", "tomorrow") from the time the customer said it.
+- Do not book: our own promise the customer did not answer, the customer saying they will contact us, a request for a specific person to call, or a request on behalf of someone else.
+- Check the pending and the finished agreed follow-ups first ([agreed in <exchangeId> at <time>] names the message), so a promise already booked or done is not booked again.
+- One agreed follow-up per channel at a time; put any further agreed time in its note.
+- If the customer said they will do something by a time (e.g. send documents by Friday), schedule the next regular follow-up after that time instead of the day rule.`;
+/**
+ * One exchange, paging back with `before` until it has `wanted` entries or reaches the
+ * start: the newest page has callKey `conversation:<id>`, each earlier one
+ * `conversation:<id>:before:<n>`. `null` when the first read fails; a later failed page stops
+ * there and `range.from` stays above 0.
+ */
+async function readConversation(ctx, exchangeId, wanted) {
+    const first = await ctx.api.tools.readExchange({ exchangeId }, { callKey: `conversation:${exchangeId}` });
+    if (!first.ok)
+        return null;
+    let read = first.value;
+    while (read.range.from > 0 && read.entries.length < wanted) {
+        const before = read.range.from;
+        const page = await ctx.api.tools.readExchange({ exchangeId, before }, { callKey: `conversation:${exchangeId}:before:${before}` });
+        if (!page.ok || page.value.range.to !== before || page.value.range.from >= before)
+            break;
+        read = {
+            ...read,
+            range: { from: page.value.range.from, to: read.range.to },
+            entries: [...page.value.entries, ...read.entries],
+        };
+    }
+    return read;
+}
+/**
+ * The conversations that started this Run (a connected call, an SMS or email turn), read with
+ * `readExchange`: a whole call, the last {@link THREAD_MESSAGES_SHOWN} messages of a thread.
+ * A read that fails is left out.
+ */
+async function readTriggeringConversations(ctx) {
+    const read = [];
+    const seen = new Set();
+    for (const trigger of ctx.params.triggers) {
+        const conversation = (trigger.type === 'call.ended' && trigger.result === 'connected') ||
+            trigger.type === 'sms.turn-ended' ||
+            trigger.type === 'email.turn-ended';
+        if (!conversation || seen.has(trigger.exchangeId))
+            continue;
+        seen.add(trigger.exchangeId);
+        const wanted = trigger.type === 'call.ended' ? Number.POSITIVE_INFINITY : THREAD_MESSAGES_SHOWN;
+        const result = await readConversation(ctx, trigger.exchangeId, wanted);
+        if (result)
+            read.push(result);
+    }
+    return read;
+}
+/**
+ * One customer's follow-up block, in their local time: `New conversations:` (only when this
+ * customer has one: a whole call, the last messages of a thread), `Pending scheduled actions:` and
+ * `Finished agreed follow-ups (last N days):`.
+ */
+function customerSection(params, contactId, conversations) {
+    const timezone = params.activity.byContact[contactId]?.timezone ?? params.activity.timezone;
+    const said = conversations
+        .filter((conversation) => conversation.contactId === contactId)
+        .map((conversation) => render.conversation(conversation, timezone, conversation.channel === 'call' ? {} : { limit: THREAD_MESSAGES_SHOWN }));
+    const pending = params.scheduledActions.filter((action) => action.contactId === contactId);
+    const finished = params.recentAgreedActions.filter((action) => action.contactId === contactId);
+    return [
+        ...(said.length > 0 ? [`New conversations:\n${said.join('\n\n')}`] : []),
+        `Pending scheduled actions:\n${render.pendingActions(pending, timezone)}`,
+        `Finished agreed follow-ups (last ${RECENT_AGREED_ACTIONS_DAYS} days):\n${render.recentAgreedActions(finished, timezone)}`,
+    ].join('\n\n');
+}
+/**
+ * The rules after the company's own: applying day-N rules and keeping agreed follow-ups, every Run;
+ * booking agreed follow-ups too when the Run read a conversation.
+ */
+function rules(conversations) {
+    return [DAY_RULES, AGREED_RULES, ...(conversations.length > 0 ? [BOOKING_RULES] : [])].join('\n\n');
+}
+export const followUps = { readTriggeringConversations, customerSection, rules };
+//# sourceMappingURL=follow-ups.js.map