@fugood/buttress-server 2.26.0-beta.1 → 2.26.0-beta.2

package/lib/functions/types.d.ts

@@ -1,6 +1,7 @@
 import type { Backend } from '../index';
 import type { Config } from '../types';
 import type { VerifiedIdentity } from '../utils/buttressAuth';
+import type { WorkspaceState } from '../utils/workspaceState';
 /**
  * Declarative metadata a local function file exports alongside its handler.
  *
@@ -12,6 +13,23 @@ export type FunctionMeta = {
     parameters?: Record<string, any>;
     /** Per-function deadline. Number of ms, or an `ms()` string like "10m". */
     timeout?: number | string;
+    /**
+     * `true` declares the file as a daemon: a long-lived background function.
+     * Its default export runs once, with a `DaemonContext`, and stays alive —
+     * timers (`context.setInterval`), Data Bank subscriptions
+     * (`context.bank.subscribe`) and event handlers (`context.onEvent`) keep
+     * firing until the file changes or the server stops. Daemon files are not
+     * exposed as MCP tools or callable endpoints, and `timeout` does not apply
+     * to them.
+     */
+    daemon?: boolean;
+};
+/** An event another local function sent via `context.daemons.emit`. */
+export type DaemonEmittedEvent = {
+    event: string;
+    data?: unknown;
+    /** Name of the local function (or daemon) that emitted it. */
+    source: string;
 };
 export type FunctionEmit = (event: string, data?: unknown) => void;
 export type SpawnOptions = {
@@ -102,6 +120,72 @@ export type SynthesizeResult = {
     sampling_rate: number;
     channels: number;
 };
+/** 'InSubspace' scopes a property to the space; 'Global' is cross-application. */
+export type BankPropertyMeta = 'InSubspace' | 'Global';
+export type BankProperty = {
+    propertyId: string;
+    meta: BankPropertyMeta;
+    definition: Record<string, any> | null;
+    value: any;
+    tags: string[] | null;
+    lastUpdateHash: string | null;
+    lastUpdateNote: string | null;
+    lastUpdateKey: string | null;
+    createAt: string | null;
+    updateAt: string | null;
+};
+export type BankListOptions = {
+    /** Match against definition title/description or tags. */
+    keyword?: string;
+    meta?: BankPropertyMeta;
+    /** Restrict to these property ids. */
+    ids?: string[];
+};
+/**
+ * The Bank replaces `value` unconditionally on update — an omitted `value`
+ * clears the stored one. Read-merge first when a partial update is intended.
+ */
+export type BankPropertyInput = {
+    propertyId: string;
+    /** Defaults to 'InSubspace'. */
+    meta?: BankPropertyMeta;
+    definition?: Record<string, any>;
+    newDefinitionFallback?: Record<string, any>;
+    value?: any;
+    updateNote?: string;
+    /** Bank defaults upsert to true; pass false to require an existing property. */
+    upsert?: boolean;
+    tags?: string[];
+};
+export type BankUpdateOptions = {
+    /** Skip notifying subscribed devices about this update. */
+    dontNotify?: boolean;
+};
+/** A live Data Bank change subscription (daemon functions only). */
+export type BankSubscriptionHandle = {
+    close: () => void;
+};
+/** Remote Data Bank access for the bound workspace. */
+export type BankContext = {
+    list: (options?: BankListOptions) => Promise<BankProperty[]>;
+    /** Null when the property does not exist. */
+    get: (propertyId: string) => Promise<BankProperty | null>;
+    update: (properties: BankPropertyInput[], options?: BankUpdateOptions) => Promise<BankProperty[]>;
+    remove: (propertyId: string) => Promise<boolean>;
+    /**
+     * Watch property ids for remote changes. Only available inside daemon
+     * functions — a call-scoped function has no lifetime to attach it to.
+     * Closed automatically when the daemon stops.
+     */
+    subscribe: (propertyIds: string[], onChange: (properties: BankProperty[]) => void) => BankSubscriptionHandle;
+};
+/** What the executor needs to route `context.daemons` calls. */
+export type DaemonsHub = {
+    /** Enqueue an `event` invocation on a running daemon; throws when unknown. */
+    emit: (name: string, event: string, data: unknown, source: string) => void;
+    /** Names of the daemons currently running. */
+    names: () => string[];
+};
 /** The second argument every local function handler receives. */
 export type FunctionContext = {
     spawn: (command: string, args?: string[], options?: SpawnOptions) => Promise<SpawnResult>;
@@ -114,6 +198,18 @@ export type FunctionContext = {
         transcribe: (options: TranscribeOptions) => Promise<any>;
         synthesize: (options: SynthesizeOptions) => Promise<SynthesizeResult>;
     };
+    /**
+     * Workspace Data Bank (read/write, v1 — no subscribe). Every method throws
+     * until credentials are stored via `bricks buttress bank-key`.
+     */
+    bank: BankContext;
+    /** Signal running daemon functions from any local function (or daemon). */
+    daemons: {
+        /** Deliver an event to the named daemon. Throws when it is not running. */
+        emit: (name: string, event: string, data?: unknown) => void;
+        /** Names of the daemons currently running. */
+        list: () => string[];
+    };
     fetch: typeof fetch;
     log: (...args: unknown[]) => void;
     emit: FunctionEmit;
@@ -131,12 +227,30 @@ export type FunctionContext = {
     libs: Record<string, any>;
 };
 export type FunctionHandler = (input: any, context: FunctionContext) => any;
+/**
+ * The context a daemon's default export receives (as its only argument):
+ * everything a function gets, plus lifetime APIs. Registered timers,
+ * subscriptions and event handlers stay live after the invocation returns.
+ */
+export type DaemonContext = FunctionContext & {
+    /**
+     * A managed `setInterval`: the callback keeps firing until cleared or the
+     * daemon stops; a callback that throws is logged and never stops the timer.
+     */
+    setInterval: (callback: () => unknown, ms: number) => NodeJS.Timeout;
+    clearInterval: (handle: NodeJS.Timeout) => void;
+    /** Receive events other local functions send via `context.daemons.emit`. */
+    onEvent: (handler: (event: DaemonEmittedEvent) => unknown) => void;
+};
+export type DaemonHandler = (context: DaemonContext) => any;
 export type LoadedFunction = {
     name: string;
     file: string;
     meta: FunctionMeta;
     handler: FunctionHandler;
     timeoutMs: number;
+    /** True for daemon files (`meta.daemon = true`). */
+    daemon?: boolean;
     /** Every file in this function's module graph → mtimeMs when it was loaded. */
     files: Map<string, number>;
 };
@@ -145,6 +259,11 @@ export type FunctionSummary = {
     description: string;
     parameters: Record<string, any>;
 };
+/** What `GET /functions` and the status page report about a daemon. */
+export type DaemonSummary = {
+    name: string;
+    description: string;
+};
 export type FunctionsConfig = {
     enabled: boolean;
     dir: string;
@@ -162,6 +281,8 @@ export type FunctionsConfig = {
 export type FunctionRuntime = {
     backend: Backend;
     config: Config;
+    /** Carries the Data Bank binding; absent means `context.bank` is unconfigured. */
+    workspaceState?: WorkspaceState;
 };
 /** Metadata an `_auth` file exports alongside its authorize handler. */
 export type AuthMeta = {