@listen1954/board 0.1.0

package/lib/index.js

@@ -0,0 +1,56 @@
+import Schema from '@deepseek-ai/schemastery';
+import { createBoardService } from './service.js';
+import { BoardStore, resolveBoardRoot } from './store.js';
+import { registerBoardTools } from './tools.js';
+import { registerBoardRpc } from './rpc.js';
+import { BOARD_SYSTEM_PROMPT } from './prompt.js';
+export const name = 'board';
+export const inject = ['tools'];
+export const Config = Schema.object({
+    wakeOnGlobalReminder: Schema.boolean().default(false),
+});
+export function apply(ctx, config = { wakeOnGlobalReminder: false }) {
+    const store = new BoardStore(resolveBoardRoot());
+    const service = createBoardService(ctx, store, {
+        wakeOnGlobalReminder: config.wakeOnGlobalReminder ?? false,
+    });
+    registerBoardRpc(ctx, service);
+    registerBoardTools(ctx);
+    ctx.effect(() => {
+        let running = false;
+        const scan = async () => {
+            if (running)
+                return;
+            running = true;
+            try {
+                const events = await service.fireDue();
+                for (const event of events) {
+                    for (const reminder of event.fired) {
+                        ctx.logger.info(`[board] reminder fired: ${reminder.title} (${event.scope})`);
+                    }
+                }
+            }
+            catch (error) {
+                ctx.logger.error(`[board] reminder scan failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            finally {
+                running = false;
+            }
+        };
+        const timer = setInterval(() => { void scan(); }, 3000);
+        timer.unref();
+        void scan();
+        return () => clearInterval(timer);
+    }, 'board: reminder scheduler');
+    ctx.inject(['systemPrompt'], (promptCtx) => {
+        promptCtx.systemPrompt.section({
+            name: 'board',
+            order: 210,
+            text: BOARD_SYSTEM_PROMPT,
+        });
+    });
+    ctx.logger.info('[board] ready');
+}
+export { BoardNotFoundError, BoardOpError, BoardRevisionError } from './domain.js';
+export { BoardModel, BoardService } from './service.js';
+export { BoardStore, resolveBoardRoot, resolveDshHome } from './store.js';

package/lib/prompt.d.ts

@@ -0,0 +1,2 @@
+/** Short system-prompt section. Card bodies stay out of the prompt. */
+export declare const BOARD_SYSTEM_PROMPT: string;

package/lib/prompt.js

@@ -0,0 +1,18 @@
+/** Short system-prompt section. Card bodies stay out of the prompt. */
+export const BOARD_SYSTEM_PROMPT = [
+    'You have one unified Board. The global view contains all normal and session-linked columns; session scope projects only this conversation\'s task column.',
+    'An agent in any conversation may use global scope to read and modify the entire board. Use session scope only when the user explicitly means this conversation or the new task clearly belongs to it.',
+    'Choose tools by intent: board_list is only for an overview of both global and current-session summaries; board_search directly finds existing cards by title, notes, logs, attachment names, or current/historical columns; board_get reads one known card or the full board; board_apply changes data.',
+    'Do not call board_list before every operation. When the user names or describes an existing task but provides no ID, search global unless they explicitly restrict the request to this session.',
+    'Capability map: addColumn creates a column; addCard creates a task; renameColumn/updateCard edit title, notes, startAt/endAt, and task-time notifications; addLog appends an immutable progress note or blocker; moveCard/reorderColumns organize; archiveCard completes; restoreCard/restoreCards recover; deleteCard/deleteCards permanently delete only on explicit request.',
+    'Never guess IDs. Resolve an unknown target once with board_search or board_list, then reuse IDs and the updated board returned by successful board_apply calls. If an operation fails, refresh once, correct its arguments, and do not repeat the identical failed call.',
+    'If this session has no column, call addColumn once in session scope before adding cards. Never add a second session column.',
+    'The session UI intentionally hides the column concept even though its tasks live in that unified session-linked column.',
+    'Use updateCard to save title, notes, task times, and the timeReminder switch together; use moveCard/reorderColumns for organization.',
+    'Completing a card means archiveCard, not deleteCard. board_list reports archived counts; use board_get on the full board to inspect archivedAt, then restoreCard with a target column to recover one.',
+    'Use delete operations only when the user explicitly asks to delete data.',
+    'todo_write is this turn\'s short-lived plan. Board is for things the user wants to keep across turns.',
+    'When timeReminder is true, the board notifies once at startAt and once at endAt. Either task time may be null; when both exist startAt must be earlier than endAt.',
+    'If scope is omitted: use board_list for an overview, search global for an existing task, and create in session only when the request is tied to this conversation; otherwise ask where to create it.',
+    'Do not put card notes into this prompt; fetch them with board_get when needed.',
+].join(' ');

package/lib/rpc.d.ts

@@ -0,0 +1,21 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { AttachmentDownload, AttachmentUpload, Board, BoardScope, MutateOp } from './domain.js';
+type BoardRpcTarget = {
+    getBoard(sessionId: string, scope: BoardScope, defaultColumns?: string[]): Promise<Board>;
+    mutate(sessionId: string, scope: BoardScope, op: MutateOp, revision: number): Promise<Board>;
+    addLog(sessionId: string, scope: BoardScope, cardId: string, text: string, attachments: AttachmentUpload[], revision: number): Promise<Board>;
+    getAttachment(sessionId: string, scope: BoardScope, cardId: string, attachmentId: string): Promise<AttachmentDownload>;
+    openAttachment(sessionId: string, scope: BoardScope, cardId: string, attachmentId: string): Promise<{
+        opened: true;
+    }>;
+};
+export declare const BOARD_RPC_CHANNEL = "/board-rpc";
+/** Host Connection is optional: tools still work in assemblies without a web carrier. */
+export declare function registerBoardRpc(ctx: Context, service: BoardRpcTarget): void;
+export declare function dispatchBoardRpc(service: BoardRpcTarget, endpoint: 'getBoard' | 'mutate' | 'addLog', payload: unknown): Promise<Board>;
+export declare function dispatchBoardRpc(service: BoardRpcTarget, endpoint: 'getAttachment', payload: unknown): Promise<AttachmentDownload>;
+export declare function dispatchBoardRpc(service: BoardRpcTarget, endpoint: 'openAttachment', payload: unknown): Promise<{
+    opened: true;
+}>;
+export declare function dispatchBoardRpc(service: BoardRpcTarget, endpoint: string, payload: unknown): Promise<unknown>;
+export {};

package/lib/rpc.js

@@ -0,0 +1,101 @@
+import { BoardNotFoundError, BoardOpError, BoardRevisionError } from './domain.js';
+export const BOARD_RPC_CHANNEL = '/board-rpc';
+/** Host Connection is optional: tools still work in assemblies without a web carrier. */
+export function registerBoardRpc(ctx, service) {
+    ctx.inject(['connection'], (inner) => {
+        const connection = inner.connection;
+        connection.rpc.handle(BOARD_RPC_CHANNEL, async (endpoint, payload) => {
+            try {
+                return { ok: true, value: await dispatchBoardRpc(service, endpoint, payload) };
+            }
+            catch (error) {
+                return fail(error);
+            }
+        }, { authority: 'trusted-host' });
+    });
+}
+export async function dispatchBoardRpc(service, endpoint, payload) {
+    const args = readArgs(payload);
+    const sessionId = requireString(args, 'sessionId');
+    const scope = requireScope(args.scope);
+    if (endpoint === 'getBoard') {
+        return service.getBoard(sessionId, scope, readDefaultColumns(args.defaultColumns));
+    }
+    if (endpoint === 'mutate') {
+        const op = args.op;
+        if (op === undefined || typeof op !== 'object' || op === null || Array.isArray(op)) {
+            throw new BoardOpError('mutate requires op');
+        }
+        const revision = args.revision;
+        if (typeof revision !== 'number' || !Number.isInteger(revision)) {
+            throw new BoardOpError('mutate requires integer revision');
+        }
+        return service.mutate(sessionId, scope, op, revision);
+    }
+    if (endpoint === 'addLog') {
+        const attachments = args.attachments;
+        if (!Array.isArray(attachments))
+            throw new BoardOpError('addLog requires attachments');
+        return service.addLog(sessionId, scope, requireString(args, 'cardId'), typeof args.text === 'string' ? args.text : '', attachments, requireRevision(args.revision, 'addLog'));
+    }
+    if (endpoint === 'getAttachment') {
+        return service.getAttachment(sessionId, scope, requireString(args, 'cardId'), requireString(args, 'attachmentId'));
+    }
+    if (endpoint === 'openAttachment') {
+        return service.openAttachment(sessionId, scope, requireString(args, 'cardId'), requireString(args, 'attachmentId'));
+    }
+    throw new BoardOpError(`unknown board rpc: ${endpoint}`);
+}
+function requireRevision(value, endpoint) {
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        throw new BoardOpError(`${endpoint} requires integer revision`);
+    return value;
+}
+function readArgs(payload) {
+    if (!isPlainObject(payload) || !isPlainObject(payload.args) || Reflect.ownKeys(payload).length !== 1) {
+        throw new BoardOpError('Remote payload must contain exactly one plain-object args field');
+    }
+    return payload.args;
+}
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new BoardOpError(`args.${key} must be a non-empty string`);
+    }
+    return value;
+}
+function requireScope(value) {
+    if (value === 'global' || value === 'session')
+        return value;
+    throw new BoardOpError('args.scope must be global or session');
+}
+function readDefaultColumns(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length !== 3 || value.some((title) => typeof title !== 'string' || title.trim().length === 0)) {
+        throw new BoardOpError('args.defaultColumns must contain three non-empty strings');
+    }
+    return value;
+}
+function fail(error) {
+    if (error instanceof BoardRevisionError) {
+        return { ok: false, error: { code: 'internal', message: error.message, details: {} } };
+    }
+    if (error instanceof BoardNotFoundError || error instanceof BoardOpError) {
+        return { ok: false, error: { code: 'internal', message: error.message, details: {} } };
+    }
+    return {
+        ok: false,
+        error: {
+            code: 'internal',
+            message: error instanceof Error ? error.message : String(error),
+            details: {},
+        },
+    };
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}

package/lib/service.d.ts

@@ -0,0 +1,74 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { AttachmentDownload, AttachmentUpload, Board, BoardScope, BoardSummary, Card, Clock, IdFactory, MutateOp } from './domain.js';
+import { fireDueReminders } from './domain.js';
+import type { BoardStore } from './store.js';
+export interface BoardChangedEvent {
+    scope: BoardScope;
+    sessionId?: string;
+    board: Board;
+}
+export interface BoardServiceOptions {
+    now?: Clock;
+    newId?: IdFactory;
+    emit?: (event: BoardChangedEvent) => void;
+    wakeOnGlobalReminder?: boolean;
+    openFile?: (path: string) => Promise<void>;
+}
+export interface BoardReminderEvent extends BoardChangedEvent {
+    fired: ReturnType<typeof fireDueReminders>['fired'];
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        board: BoardService;
+    }
+    interface Events {
+        'board/changed'(payload: BoardChangedEvent): void;
+    }
+}
+/** Store-backed board API. Tests construct this directly (no Cordis). */
+export declare class BoardModel {
+    private readonly store;
+    readonly wakeOnGlobalReminder: boolean;
+    private readonly now;
+    private readonly createId;
+    private readonly emitChange;
+    private readonly openFile;
+    private mutationChain;
+    private migrationPromise;
+    private migrationChecked;
+    constructor(store: BoardStore, options?: BoardServiceOptions);
+    list(callerSessionId: string): Promise<BoardSummary[]>;
+    getBoard(callerSessionId: string, scope: BoardScope, defaultColumns?: string[]): Promise<Board>;
+    getCard(callerSessionId: string, scope: BoardScope, cardId: string): Promise<Card>;
+    mutate(callerSessionId: string, scope: BoardScope, op: MutateOp, revision?: number): Promise<Board>;
+    addLog(callerSessionId: string, scope: BoardScope, cardId: string, text: string, attachments: AttachmentUpload[], revision: number): Promise<Board>;
+    getAttachment(callerSessionId: string, scope: BoardScope, cardId: string, attachmentId: string): Promise<AttachmentDownload>;
+    openAttachment(callerSessionId: string, scope: BoardScope, cardId: string, attachmentId: string): Promise<{
+        opened: true;
+    }>;
+    fireDue(): Promise<BoardReminderEvent[]>;
+    private loadUnifiedGlobal;
+    private ensureLegacyMigration;
+    private migrateLegacySessionBoards;
+    private emitBoard;
+    private removeDeletedAttachments;
+    private enqueueMutation;
+}
+/** Host service: `ctx.board` plus Typert SRC Remote (`board/getBoard`, `board/mutate`). */
+export declare class BoardService extends TypertRemoteService {
+    readonly model: BoardModel;
+    constructor(ctx: Context, store: BoardStore, options?: BoardServiceOptions);
+    get wakeOnGlobalReminder(): boolean;
+    list(callerSessionId: string): Promise<BoardSummary[]>;
+    getBoard(sessionId: string, scope: BoardScope, defaultColumns?: string[]): Promise<Board>;
+    getCard(sessionId: string, scope: BoardScope, cardId: string): Promise<Card>;
+    mutate(sessionId: string, scope: BoardScope, op: MutateOp, revision: number): Promise<Board>;
+    addLog(sessionId: string, scope: BoardScope, cardId: string, text: string, attachments: AttachmentUpload[], revision: number): Promise<Board>;
+    getAttachment(sessionId: string, scope: BoardScope, cardId: string, attachmentId: string): Promise<AttachmentDownload>;
+    openAttachment(sessionId: string, scope: BoardScope, cardId: string, attachmentId: string): Promise<{
+        opened: true;
+    }>;
+    fireDue(): Promise<BoardReminderEvent[]>;
+}
+export declare function createBoardService(ctx: Context, store: BoardStore, options?: BoardServiceOptions): BoardService;