@columenlabs/lumen-ai 0.1.134 → 0.1.136

package/README.md

@@ -99,7 +99,7 @@ app.all('/api/assistant/*', (c) => routes(c.req.raw));
 - **ChatGPT sign-in.** In place of their own OpenAI key a person may sign in with their ChatGPT plan (`POST /my-signin`, then `POST /my-signin/finish {url}`): the sign-in opens in a new tab and ends on `http://127.0.0.1:1455/auth/callback`, a page that does not load, whose address the person pastes back. The tokens are sealed as their own key and refreshed before they run out; answers on the plan count tokens and no dollars.
 - **Who pays.** The person's pick (the shared keys by default) while it has a key for the tier's provider and money left this month under its cap (an admin sets the shared keys' cap per person, `PUT /app`), else the other; with neither the panel says why.
 - **Tools.** Each group is Off, Read, Read + draft or Read + write per person. A tool is a read when its MCP `readOnlyHint` is set. On Read + draft a write only drafts a card, and runs as the person when they press Save, after access is checked again. Read + write is offered only for a group with `writes: true`: its writes run at once, and with `undo` set each one's line in the chat has Undo, which calls `undo(caller, { tool, args, result })` (`POST /chats/:id/writes/:step/undo`); the model is told what was undone. Cards drafted one after another show as one stack with Save all. Use `mcpServerTools` (an SDK `McpServer`), `mcpFetchTools` (a server served as a fetch handler, any SDK), `remoteMcpTools` or `plainTools`.
-- **Web.** `fetch` is a plain GET from the Worker (10 s, 2 MB, never the app's own hosts or private addresses). ScrapeQL's own tools join over its MCP API once an admin pastes a Cloudflare Access service token (`PUT /web/scrapeql`).
+- **Web.** `fetch` is a plain GET from the Worker (10 s, 2 MB, never the app's own hosts or private addresses). ScrapeQL's own tools join over its MCP API once an admin pastes a Cloudflare Access service token (`PUT /web/scrapeql`). A Worker on ScrapeQL's own Cloudflare account passes its service binding instead, `scrapeql: { url: 'https://scrapeql/mcp', fetch: env.SCRAPEQL.fetch.bind(env.SCRAPEQL) }`: no token is stored, the tools are always on and Settings shows the link with a Test.
 - **Hand off and advice.** The `escalate` tool hands one task to a higher tier (the person sets next, any or only when asked); Anthropic's advisor tool lets a higher tier send a plan, at most two an answer.
 - **Chats** stream as server-sent events (`POST /chat`); closing the request stops the answer and keeps what was said. Past 150k tokens, or on `/compact`, the history sent to the model becomes a summary. Run `assistant.purge()` once a day to drop chats 30 days after their last message.
 
@@ -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';
@@ -123,9 +124,13 @@ export interface AssistantOptions {
     web?: {
         /** `fetch` options, or false for no fetch. */
         fetch?: WebFetchOptions | false;
-        /** ScrapeQL's MCP address; its tools join once an admin adds the Access token. */
+        /**
+         * ScrapeQL's MCP address; its tools join once an admin adds the Access token. With `fetch`
+         * (a service binding's), ScrapeQL is reached through it: no token, its tools always on.
+         */
         scrapeql?: {
             url: string;
+            fetch?: typeof fetch;
         };
     };
     store: AssistantStore;
@@ -136,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. */
@@ -252,8 +264,10 @@ export declare class Assistant {
         detail: string;
         at: number;
     }>;
-    /** Lists ScrapeQL's tools with the token: works or why not. */
-    testScrapeql(token: AccessToken): Promise<{
+    /** ScrapeQL is reached over a service binding, so it needs no token. */
+    get boundScrapeql(): boolean;
+    /** Lists ScrapeQL's tools with the token (none over a binding): works or why not. */
+    testScrapeql(token: AccessToken | null): Promise<{
         ok: boolean;
         detail: string;
         at: number;

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';
@@ -357,9 +358,11 @@ export class Assistant {
             web: {
                 fetch: p.web ?? true,
                 scrapeql: this.o.web?.scrapeql
-                    ? caller.admin
-                        ? keyState(scrapeql, (d) => d.client_id)
-                        : { set: !!scrapeql }
+                    ? this.o.web.scrapeql.fetch
+                        ? { set: true, bound: true }
+                        : caller.admin
+                            ? keyState(scrapeql, (d) => d.client_id)
+                            : { set: !!scrapeql }
                     : null,
             },
             providers,
@@ -525,12 +528,13 @@ export class Assistant {
                     access: 'read',
                     source: webFetchTools(this.o.web?.fetch || {}),
                 });
-            const sq = this.o.web?.scrapeql ? await this.state.scrapeql() : null;
-            if (sq && this.o.web?.scrapeql)
+            const sq = this.o.web?.scrapeql;
+            const token = sq && !sq.fetch ? await this.state.scrapeql() : null;
+            if (sq && (sq.fetch || token))
                 sources.push({
                     group: 'web',
                     access: 'read',
-                    source: scrapeqlTools(this.o.web.scrapeql.url, sq, this.o.fetch),
+                    source: scrapeqlTools(sq.url, token, sq.fetch ?? this.o.fetch),
                 });
         }
         const results = await Promise.allSettled(sources.map((s) => s.source()));
@@ -708,7 +712,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`
                     : '') +
@@ -831,7 +843,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.',
@@ -1636,20 +1648,30 @@ export class Assistant {
             return { ok: false, detail: shownError(err).message, at };
         }
     }
-    /** Lists ScrapeQL's tools with the token: works or why not. */
+    /** ScrapeQL is reached over a service binding, so it needs no token. */
+    get boundScrapeql() {
+        return !!this.o.web?.scrapeql?.fetch;
+    }
+    /** Lists ScrapeQL's tools with the token (none over a binding): works or why not. */
     async testScrapeql(token) {
         const at = Date.now();
-        const url = this.o.web?.scrapeql?.url;
-        if (!url)
+        const sq = this.o.web?.scrapeql;
+        if (!sq)
             return { ok: false, detail: 'ScrapeQL is not set up in this app.', at };
         try {
-            const open = await scrapeqlTools(url, token, this.o.fetch)();
+            const open = await scrapeqlTools(sq.url, sq.fetch ? null : token, sq.fetch ?? this.o.fetch)();
             const n = open.tools.length;
             await open.close();
             return { ok: true, detail: `ScrapeQL answered with ${n} tool${n === 1 ? '' : 's'}.`, at };
         }
         catch {
-            return { ok: false, detail: 'ScrapeQL refused the token or could not be reached.', at };
+            return {
+                ok: false,
+                detail: sq.fetch
+                    ? 'ScrapeQL could not be reached over the link.'
+                    : 'ScrapeQL refused the token or could not be reached.',
+                at,
+            };
         }
     }
     // ---------------------------------------------------------------- drafts

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

@@ -273,6 +273,8 @@ export function assistantRoutes(app, o) {
                     const no = admin();
                     if (no)
                         return no;
+                    if (a.boundScrapeql)
+                        return fail("ScrapeQL is reached over the app's link; it needs no token.", 409, 'bound');
                     const b = await body(req);
                     const client_id = str(b.client_id, 200);
                     const client_secret = str(b.client_secret, 400);
@@ -300,6 +302,8 @@ export function assistantRoutes(app, o) {
                     const no = admin();
                     if (no)
                         return no;
+                    if (a.boundScrapeql)
+                        return json(await a.testScrapeql(null));
                     const d = await a.state.scrapeql();
                     if (!d)
                         return fail('No ScrapeQL token is set.', 404);

package/dist/assistant/web.d.ts

@@ -41,5 +41,8 @@ export interface AccessToken {
     client_id: string;
     client_secret: string;
 }
-/** ScrapeQL's MCP tools over its API, with an Access service token. Every one of them reads. */
-export declare function scrapeqlTools(url: string, token: AccessToken, f?: typeof fetch): ToolSource;
+/**
+ * ScrapeQL's MCP tools over its API, with an Access service token, or none over a service
+ * binding (`f` is then the binding's fetch). Every one of them reads.
+ */
+export declare function scrapeqlTools(url: string, token: AccessToken | null, f?: typeof fetch): ToolSource;

package/dist/assistant/web.js

@@ -155,14 +155,21 @@ export function webFetchTools(o = {}) {
         return open;
     };
 }
-/** ScrapeQL's MCP tools over its API, with an Access service token. Every one of them reads. */
+/**
+ * ScrapeQL's MCP tools over its API, with an Access service token, or none over a service
+ * binding (`f` is then the binding's fetch). Every one of them reads.
+ */
 export function scrapeqlTools(url, token, f) {
     const remote = remoteMcpTools({
         url,
-        headers: {
-            'CF-Access-Client-Id': token.client_id,
-            'CF-Access-Client-Secret': token.client_secret,
-        },
+        ...(token
+            ? {
+                headers: {
+                    'CF-Access-Client-Id': token.client_id,
+                    'CF-Access-Client-Secret': token.client_secret,
+                },
+            }
+            : {}),
         ...(f ? { fetch: f } : {}),
     });
     return async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.134",
+  "version": "0.1.136",
   "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.134",
-    "@columenlabs/lumen-ui-types": "0.1.134",
+    "@columenlabs/lumen-ops": "0.1.136",
+    "@columenlabs/lumen-ui-types": "0.1.136",
     "openai": "7.32.0",
     "zod": "^4.3.6"
   },