@columenlabs/lumen-ai 0.1.135 → 0.1.137

package/README.md

@@ -141,3 +141,18 @@ The panel's composer lists what can follow three keys as they are typed. The kit
   `target` lights the thing on screen while its row is hovered. A page's source replaces a standing one with the same `id`.
 
   Text the person highlights on the page is offered first under `#` (Selected text), with where it sits from the nearest `data-assistant-where` attribute. To hand a highlight over from the page, an Ask button calls `composeAssistant({ refs: [selectionRef({ text, where })], text: '' })` (or any refs and text): the panel opens with the chips in the composer, focused for the person to finish.
+
+### Bearings
+
+Each message the model gets starts with a few lines of bearings: the time now in the person's zone (the panel sends the browser's), UTC, how long since the chat's last message and the app's name. They go in the message, not the system prompt, so the prompt cache holds. An app adds its own lines with `bearings`; each call gets 300 ms, and when it is late or throws its lines are left out.
+
+```ts
+createAssistant({
+  // ...
+  app: 'Notes',
+  timeZone: 'America/Los_Angeles', // when the browser sends none
+  bearings: ({ now, at, span }) => `Next backup: ${at(nextBackup(now))} (in ${span(nextBackup(now) - now)})`,
+});
+```
+
+An app with its own assistant loop builds the same block with `bearings({ timeZone, lastAt, app, extras })` and puts it before the message.

package/dist/assistant/bearings.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Bearings: a few lines at the top of each message telling the model when and where it is (the time
+ * in the person's zone, how long since the chat's last message, the app), so it never guesses
+ * "today". Kept out of the system prompt so the prompt cache holds. An app adds its own lines (a
+ * market's session, a billing day) through `extras`; each gets `extrasMs` and is left out when it is
+ * late or throws, so bearings never hold a turn.
+ */
+/** What an app's extra lines are worked out from. */
+export interface BearingsNow {
+    /** The moment, ms since the epoch. */
+    now: number;
+    /** The person's IANA zone (checked). */
+    timeZone: string;
+    /** A moment in the person's zone: `Tue, Oct 27, 2026, 3:05 PM PDT`. */
+    at: (ms: number) => string;
+    /** A span as the model reads it: `1h 55m`, `2d 3h`. */
+    span: (ms: number) => string;
+}
+/** An app's own bearings: lines (or one line) to add, nothing to add none. */
+export type BearingsExtra = (b: BearingsNow) => string | string[] | null | undefined | Promise<string | string[] | null | undefined>;
+export interface BearingsInput {
+    /** The moment; now by default. */
+    now?: number;
+    /** The person's IANA zone (the browser's); `fallbackZone` when missing or unknown. */
+    timeZone?: string;
+    /** UTC by default. */
+    fallbackZone?: string;
+    /** When this chat's last message was, ms; left out on a new chat. */
+    lastAt?: number;
+    /** The app's name (`App: …`). */
+    app?: string;
+    extras?: BearingsExtra | BearingsExtra[];
+    /** How long each extra may take; 300 ms. */
+    extrasMs?: number;
+}
+/** `zone` when Intl knows it, else undefined. */
+export declare function knownZone(zone: string | undefined): string | undefined;
+/** A moment in `timeZone`: `Tue, Oct 27, 2026, 3:05 PM PDT`. */
+export declare function bearingTime(ms: number, timeZone: string): string;
+/** A span: `45s`, `12m`, `1h 55m`, `2d 3h`. */
+export declare function bearingSpan(ms: number): string;
+/** The bearings block, ending in a blank line, to put before the person's message. */
+export declare function bearings(input?: BearingsInput): Promise<string>;

package/dist/assistant/bearings.js

@@ -0,0 +1,101 @@
+/**
+ * Bearings: a few lines at the top of each message telling the model when and where it is (the time
+ * in the person's zone, how long since the chat's last message, the app), so it never guesses
+ * "today". Kept out of the system prompt so the prompt cache holds. An app adds its own lines (a
+ * market's session, a billing day) through `extras`; each gets `extrasMs` and is left out when it is
+ * late or throws, so bearings never hold a turn.
+ */
+const EXTRAS_MS = 300;
+/** `zone` when Intl knows it, else undefined. */
+export function knownZone(zone) {
+    if (!zone || zone.length > 64)
+        return undefined;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: zone });
+        return zone;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A moment in `timeZone`: `Tue, Oct 27, 2026, 3:05 PM PDT`. */
+export function bearingTime(ms, timeZone) {
+    return new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        weekday: 'short',
+        month: 'short',
+        day: 'numeric',
+        year: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+        timeZoneName: 'short',
+    }).format(ms);
+}
+/** A span: `45s`, `12m`, `1h 55m`, `2d 3h`. */
+export function bearingSpan(ms) {
+    const m = Math.round(Math.abs(ms) / 60_000);
+    if (m < 1)
+        return `${Math.round(Math.abs(ms) / 1000)}s`;
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return m % 60 ? `${h}h ${m % 60}m` : `${h}h`;
+    const d = Math.floor(h / 24);
+    return h % 24 ? `${d}d ${h % 24}h` : `${d}d`;
+}
+function ago(ms) {
+    const m = ms / 60_000;
+    if (m < 1)
+        return 'just now';
+    if (m < 60)
+        return `${Math.round(m)} min ago`;
+    const h = m / 60;
+    if (h < 24)
+        return `${Math.round(h)} h ago`;
+    const d = Math.round(h / 24);
+    return `${d} day${d === 1 ? '' : 's'} ago`;
+}
+async function within(extra, b, ms) {
+    let timer;
+    const late = new Promise((done) => {
+        timer = setTimeout(() => done(undefined), ms);
+    });
+    try {
+        const got = await Promise.race([Promise.resolve().then(() => extra(b)), late]);
+        if (!got)
+            return [];
+        return (Array.isArray(got) ? got : [got]).filter((l) => typeof l === 'string' && l.trim());
+    }
+    catch {
+        return [];
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The bearings block, ending in a blank line, to put before the person's message. */
+export async function bearings(input = {}) {
+    const now = input.now ?? Date.now();
+    const timeZone = knownZone(input.timeZone) ?? knownZone(input.fallbackZone) ?? 'UTC';
+    const b = {
+        now,
+        timeZone,
+        at: (ms) => bearingTime(ms, timeZone),
+        span: bearingSpan,
+    };
+    const utc = new Date(now).toISOString().slice(11, 16);
+    const lines = [
+        "Bearings (the server's clock: use it for today, now and how long ago; never guess the date):",
+        `Now: ${b.at(now)} (${timeZone}) · ${utc} UTC`,
+    ];
+    if (input.lastAt && input.lastAt < now)
+        lines.push(`Last message in this chat: ${ago(now - input.lastAt)} (${b.at(input.lastAt)})`);
+    if (input.app)
+        lines.push(`App: ${input.app}`);
+    const extras = input.extras ? (Array.isArray(input.extras) ? input.extras : [input.extras]) : [];
+    const more = await Promise.all(extras.map((e) => within(e, b, input.extrasMs ?? EXTRAS_MS)));
+    for (const l of more.flat())
+        lines.push(l.slice(0, 400));
+    return `${lines.join('\n')}\n\n`;
+}

package/dist/assistant/engine.d.ts

@@ -1,4 +1,5 @@
 import type { AllowanceRequest, AllowanceState, AllowanceUnit, AssistantAccess, AssistantChat, AssistantChatRow, AssistantMessage, AssistantOwnWay, AssistantProvider, AssistantStatus, DraftItem, StepItem } from '@columenlabs/lumen-ui-types/assistant';
+import { type BearingsExtra, type BearingsNow } from './bearings.js';
 import { type ModelDef, type TaskDef, type TierDef } from './models.js';
 import { State } from './state.js';
 import { type AssistantStore, type Sealer } from './store.js';
@@ -140,8 +141,15 @@ export interface AssistantOptions {
     defaultCap?: number;
     /** An allowance on the shared keys a person can ask to raise (Request more). */
     allowance?: AllowanceOptions;
-    /** Months and dates in this zone; UTC by default. */
+    /** Months and dates in this zone, and a person's zone when their browser sends none; UTC by default. */
     timeZone?: string;
+    /** The app's name, told to the model in its bearings (`App: …`). */
+    app?: string;
+    /**
+     * The app's own lines for the bearings at the top of each message (a market's session, a billing
+     * day). Given 300 ms; late or failing, its lines are left out.
+     */
+    bearings?: (b: BearingsNow, caller: Caller) => ReturnType<BearingsExtra>;
     /** Chats are deleted this many days after their last message (`purge`); 30. */
     keepDays?: number;
     /** The fetch the model providers and ScrapeQL calls go through. */

package/dist/assistant/engine.js

@@ -19,6 +19,7 @@
 import Anthropic from '@anthropic-ai/sdk';
 import { HAND_OFF_WHYS } from '@columenlabs/lumen-ui-types/assistant';
 import OpenAI from 'openai';
+import { bearings } from './bearings.js';
 import { CHATGPT_REDIRECT, SigninError, finishChatgpt, startChatgpt, testChatgpt, } from './chatgpt.js';
 import { ALL_MODELS, DEFAULT_OUT, Meter, PROVIDERS, effortParams, } from './models.js';
 import { DEFAULT_CAP, State, keyDocName, keyState, planDocName, waitText, } from './state.js';
@@ -275,6 +276,8 @@ export class Assistant {
     async status(caller) {
         const main = await this.mainTier(caller);
         const mainModel = (await this.pick(caller, main)).model;
+        // The binding's last test has no token doc to sit in; it is read beside the rest.
+        const linkTest = this.o.web?.scrapeql?.fetch ? this.state.scrapeqlLink() : null;
         const [p, providers, scrapeql, spend, appCap, ownCap, { paying, wait }] = await Promise.all([
             this.state.person(caller.id),
             Promise.all(this.providers.map(async (id) => {
@@ -308,6 +311,7 @@ export class Assistant {
             this.state.ownCap(caller.id),
             this.state.paying(caller.id, mainModel.provider),
         ]);
+        const link = await linkTest;
         const tiers = await Promise.all(this.tiers.map(async (t) => {
             const { model, effort } = await this.pick(caller, t);
             return {
@@ -358,7 +362,11 @@ export class Assistant {
                 fetch: p.web ?? true,
                 scrapeql: this.o.web?.scrapeql
                     ? this.o.web.scrapeql.fetch
-                        ? { set: true, bound: true }
+                        ? {
+                            set: true,
+                            bound: true,
+                            ...(link?.test ? { test: link.test } : {}),
+                        }
                         : caller.admin
                             ? keyState(scrapeql, (d) => d.client_id)
                             : { set: !!scrapeql }
@@ -711,7 +719,15 @@ export class Assistant {
                     return;
                 }
             }
-            const page = this.cardNews(doc) +
+            const told = await bearings({
+                timeZone: req.time_zone,
+                fallbackZone: this.o.timeZone,
+                lastAt: prev?.at,
+                app: this.o.app,
+                ...(this.o.bearings ? { extras: (b) => this.o.bearings?.(b, caller) } : {}),
+            });
+            const page = told +
+                this.cardNews(doc) +
                 (req.refs?.length
                     ? `The person points at these parts: they are what "this" means, and when the person asks for a change they are the only parts to change. Read anything else you need (the rest of the page, other records, your tools) for context, but leave it as it is unless they ask.\n${JSON.stringify(req.refs).slice(0, 16000)}\n\n`
                     : '') +
@@ -834,7 +850,7 @@ export class Assistant {
     /** What the kit adds to the app's instructions: tools, drafts, hand off, advice, limits. */
     rules(main, policy, advisor, fns, failed) {
         const lines = [
-            `You are ${this.name}. Today is ${new Date().toISOString().slice(0, 10)}.`,
+            `You are ${this.name}. Each message starts with Bearings: the time now in the person's zone and where they are. Take today, now and how long ago from it; never guess the date.`,
             'Answer in short plain sentences. Use the tools for facts; never guess a number a tool can give you. Call several tools at once when they do not depend on each other.',
             'A tool marked DRAFT ONLY makes a card the person saves or dismisses; it changes nothing by itself. Say what the card will do; never claim it is done. The next message tells you how each card ended.',
             'A tool marked WRITES AT ONCE makes its change when you call it; the person can undo it from the chat. Change only what they asked for, and say what you changed.',

package/dist/assistant/index.d.ts

@@ -12,6 +12,7 @@
  * The ChatGPT plan sign-in's parts are exported on their own too, for an app that keeps the tokens and
  * calls OpenAI itself (`LumenChatgptSignin` is the panel's part for it).
  */
+export * from './bearings.js';
 export * from './chatgpt.js';
 export * from './engine.js';
 export * from './models.js';

package/dist/assistant/index.js

@@ -12,6 +12,7 @@
  * The ChatGPT plan sign-in's parts are exported on their own too, for an app that keeps the tokens and
  * calls OpenAI itself (`LumenChatgptSignin` is the panel's part for it).
  */
+export * from './bearings.js';
 export * from './chatgpt.js';
 export * from './engine.js';
 export * from './models.js';

package/dist/assistant/routes.js

@@ -33,7 +33,7 @@
 import { ASSISTANT_ACCESS, ASSISTANT_EFFORTS, ASSISTANT_OWN_WAYS, ASSISTANT_PAYERS, HAND_OFF_POLICIES, } from '@columenlabs/lumen-ui-types/assistant';
 import { AssistantError } from './engine.js';
 import { PROVIDERS } from './models.js';
-import { keyDocName, planDocName } from './state.js';
+import { keyDocName, planDocName, } from './state.js';
 import { APP_SCOPE } from './store.js';
 const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 const MAX_MESSAGE = 20_000;
@@ -302,8 +302,11 @@ export function assistantRoutes(app, o) {
                     const no = admin();
                     if (no)
                         return no;
-                    if (a.boundScrapeql)
-                        return json(await a.testScrapeql(null));
+                    if (a.boundScrapeql) {
+                        const test = await a.testScrapeql(null);
+                        await docs.write(APP_SCOPE, 'scrapeql:link', { test });
+                        return json(test);
+                    }
                     const d = await a.state.scrapeql();
                     if (!d)
                         return fail('No ScrapeQL token is set.', 404);

package/dist/assistant/state.d.ts

@@ -181,6 +181,10 @@ export declare class State {
     /** USD a month on the person's own keys. */
     ownCap(id: string): Promise<number>;
     scrapeql(): Promise<TokenDoc | null>;
+    /** The last test of ScrapeQL over the app's service binding (no token to keep it beside). */
+    scrapeqlLink(): Promise<{
+        test: KeyTest;
+    } | null>;
     appCap(): Promise<number>;
     spend(id: string, month?: string): Promise<SpendDoc>;
     /** Adds an answer's use to this month's spend, by label and payer. */

package/dist/assistant/state.js

@@ -183,6 +183,10 @@ export class State {
     scrapeql() {
         return this.docs.read(APP_SCOPE, 'scrapeql');
     }
+    /** The last test of ScrapeQL over the app's service binding (no token to keep it beside). */
+    scrapeqlLink() {
+        return this.docs.read(APP_SCOPE, 'scrapeql:link');
+    }
     async appCap() {
         return (await this.app()).cap_usd ?? this.o.defaultCap;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.135",
+  "version": "0.1.137",
   "description": "Lumen's assistant and agent parts: a chat assistant's server (Claude tiers, tools over MCP, the web, hand off, spend caps), serving an MCP server from a Worker, read-only tool sets and metered tool calls.",
   "license": "MIT",
   "type": "module",
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.133.0",
-    "@columenlabs/lumen-ops": "0.1.135",
-    "@columenlabs/lumen-ui-types": "0.1.135",
+    "@columenlabs/lumen-ops": "0.1.137",
+    "@columenlabs/lumen-ui-types": "0.1.137",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },