toolroll 0.5.0

package/dist/team-contract.d.ts

@@ -0,0 +1,92 @@
+import type { WorkIndexPage } from './work-index.js';
+/** Shared central-team transport contract. Requests never establish actor identity. */
+export type TeamActor = {
+    name: string;
+    generation: number;
+};
+export type TeamRole = 'viewer' | 'contributor' | 'manager';
+export type TeamLead = {
+    id: string;
+    name: string;
+    instructions: string;
+    projects: string[];
+    revision: number;
+    status: 'active' | 'paused';
+    createdBy: string;
+};
+export type TeamConversation = {
+    id: string;
+    leadId: string;
+    title: string;
+    visibility: 'private' | 'team';
+    projects: string[];
+    revision: number;
+    threadId: number;
+    createdBy: string;
+    follow: boolean;
+};
+export type TeamParticipant = {
+    account: string;
+    role: TeamRole;
+    active: boolean;
+};
+export type TeamMessage = {
+    id: number;
+    author: string;
+    role: 'operator' | 'assistant';
+    text: string;
+    status: 'queued' | 'running' | 'answered' | 'failed' | 'cancelled' | 'uncertain';
+    revision: number;
+    createdAt: string;
+    requestId: string | null;
+    turnId: number | null;
+    error: string | null;
+};
+export type TeamChatAuthorization = {
+    enabled: boolean;
+    provider: string | null;
+    model: string | null;
+    dailyTurns: number;
+    weeklyCeilingUsd: number | null;
+    conversationCeilingUsd: number | null;
+    termsDigest: string;
+    waitingReason?: string;
+};
+export type TeamSnapshot = {
+    leads: TeamLead[];
+    conversations: TeamConversation[];
+    selected: TeamConversation | null;
+    participants: TeamParticipant[];
+    messages: TeamMessage[];
+    canManage: boolean;
+    canSend: boolean;
+    canCreateLead?: boolean;
+    cursor: number;
+    truncated: boolean;
+    projects: string[];
+    accounts: string[];
+    chatAuthorization?: TeamChatAuthorization;
+    tasks?: WorkIndexPage;
+    proposals?: {
+        id: number;
+        turnId: number;
+        title: string;
+        state: string;
+        href: string;
+    }[];
+};
+export declare const TEAM_OPERATIONS: readonly ['list', 'show', 'create-lead', 'update-lead', 'create-conversation', 'member', 'send', 'edit', 'withdraw', 'read', 'authorize', 'follow', 'stop', 'transfer'];
+export type TeamOperation = typeof TEAM_OPERATIONS[number];
+export type TeamRequest = {
+    operation: TeamOperation;
+    args: Record<string, unknown>;
+};
+export type TeamResponse = {
+    version: 1;
+    ok: boolean;
+    code: string;
+    message: string;
+    result?: unknown;
+    snapshot?: TeamSnapshot;
+};
+export type TeamExecute = (actor: TeamActor, request: TeamRequest) => Promise<TeamResponse>;

package/dist/team-contract.js

@@ -0,0 +1 @@
+export const TEAM_OPERATIONS = ['list', 'show', 'create-lead', 'update-lead', 'create-conversation', 'member', 'send', 'edit', 'withdraw', 'read', 'authorize', 'follow', 'stop', 'transfer'];

package/dist/team-http.d.ts

@@ -0,0 +1,17 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type TeamActor, type TeamExecute } from './team-contract.js';
+export declare const TEAM_REQUEST_BYTES: number;
+export type TeamHttpOptions = {
+    authenticate: (request: IncomingMessage) => TeamActor | null | Promise<TeamActor | null>;
+    /** Recheck the original credential/session and current account, without extending idle expiry. */
+    revalidate: (request: IncomingMessage, actor: TeamActor) => boolean;
+    authorizeMutation: (request: IncomingMessage, actor: TeamActor) => boolean;
+    execute: TeamExecute;
+    /** Current, authorized event cursor. null means the audience is no longer available. */
+    cursor?: (actor: TeamActor, conversationId?: string) => number | null;
+    streamIntervalMs?: number;
+    streams?: Set<ServerResponse>;
+};
+/** Authenticated browser and remote CLI share one operation boundary. Streams
+ * are refresh hints only: no model calls, admissions, or completion writes. */
+export declare function handleTeamHttp(request: IncomingMessage, response: ServerResponse, options: TeamHttpOptions): Promise<boolean>;

package/dist/team-http.js

@@ -0,0 +1,144 @@
+import { TEAM_OPERATIONS } from './team-contract.js';
+export const TEAM_REQUEST_BYTES = 64 * 1024;
+const failure = (code, message) => ({ version: 1, ok: false, code, message });
+function send(response, status, value) {
+    if (response.destroyed || response.writableEnded)
+        return;
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+    response.end(JSON.stringify(value));
+}
+async function body(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > TEAM_REQUEST_BYTES)
+            throw new Error('too-large');
+        chunks.push(bytes);
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+}
+function valid(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const row = value;
+    return Object.keys(row).every(key => key === 'operation' || key === 'args') &&
+        typeof row.operation === 'string' && TEAM_OPERATIONS.includes(row.operation) &&
+        !!row.args && typeof row.args === 'object' && !Array.isArray(row.args) &&
+        !['actor', 'generation', 'authenticatedActor'].some(key => key in row.args);
+}
+/** Authenticated browser and remote CLI share one operation boundary. Streams
+ * are refresh hints only: no model calls, admissions, or completion writes. */
+export async function handleTeamHttp(request, response, options) {
+    const url = new URL(request.url ?? '/', 'http://standing-orders.local');
+    if (url.pathname !== '/api/team' && url.pathname !== '/api/team/events')
+        return false;
+    const reject = (status, code, message) => { send(response, status, failure(code, message)); request.resume(); return true; };
+    if ([...url.searchParams.keys()].some(key => /token|password|credential|authorization/i.test(key)))
+        return reject(400, 'credentials-in-url', 'Credentials never travel in URLs.');
+    const count = request.rawHeaders.filter((value, index) => index % 2 === 0 && value.toLowerCase() === 'authorization').length;
+    if (count > 1)
+        return reject(400, 'ambiguous-credentials', 'Send one authorization header.');
+    let actor;
+    try {
+        actor = await options.authenticate(request);
+    }
+    catch {
+        return reject(503, 'authentication-unavailable', 'Sign-in could not be checked.');
+    }
+    if (!actor)
+        return reject(401, 'unauthenticated', 'Sign in to continue.');
+    const conversationId = url.searchParams.get('conversation') ?? undefined;
+    if (url.pathname === '/api/team/events') {
+        if (request.method !== 'GET')
+            return reject(405, 'method-not-allowed', 'Use GET for conversation updates.');
+        let initial;
+        try {
+            initial = await options.execute(actor, { operation: conversationId ? 'show' : 'list', args: conversationId ? { conversationId } : {} });
+        }
+        catch {
+            return reject(503, 'unavailable', 'Conversation updates are unavailable.');
+        }
+        if (!initial.ok || !initial.snapshot) {
+            send(response, 403, initial);
+            return true;
+        }
+        response.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', 'x-accel-buffering': 'no' });
+        options.streams?.add(response);
+        let cursor = initial.snapshot.cursor;
+        response.write(`id: ${cursor}\nevent: change\ndata: {"cursor":${cursor}}\n\n`);
+        let active = false;
+        const close = () => { clearInterval(timer); options.streams?.delete(response); response.end(); };
+        const revoked = () => { response.write('event: revoked\ndata: {}\n\n'); close(); };
+        const tick = async () => {
+            if (active || response.destroyed || response.writableEnded)
+                return;
+            active = true;
+            try {
+                if (!options.revalidate(request, actor))
+                    return revoked();
+                let next;
+                if (options.cursor)
+                    next = options.cursor(actor, conversationId);
+                else {
+                    const reply = await options.execute(actor, { operation: conversationId ? 'show' : 'list', args: conversationId ? { conversationId } : {} });
+                    next = reply.ok ? reply.snapshot?.cursor ?? null : null;
+                }
+                if (next === null)
+                    return revoked();
+                if (next !== cursor) {
+                    cursor = next;
+                    // A slow client receives a fresh scoped snapshot on reconnect, never an unbounded replay buffer.
+                    if (!response.write(`id: ${cursor}\nevent: change\ndata: {"cursor":${cursor}}\n\n`))
+                        close();
+                }
+            }
+            catch {
+                response.write('event: unavailable\ndata: {}\n\n');
+                close();
+            }
+            finally {
+                active = false;
+            }
+        };
+        const timer = setInterval(() => { void tick(); }, options.streamIntervalMs ?? 1_000);
+        timer.unref();
+        request.once('close', close);
+        response.once('close', close);
+        return true;
+    }
+    let input;
+    if (request.method === 'GET')
+        input = { operation: conversationId ? 'show' : 'list', args: conversationId ? { conversationId } : {} };
+    else if (request.method === 'POST') {
+        if (!options.authorizeMutation(request, actor))
+            return reject(403, 'csrf', 'Your sign-in changed. Reload before sending.');
+        if (request.headers['content-type']?.split(';')[0]?.trim() !== 'application/json')
+            return reject(415, 'invalid-content-type', 'Send application/json.');
+        if (Number(request.headers['content-length'] ?? 0) > TEAM_REQUEST_BYTES)
+            return reject(413, 'request-too-large', 'That message is too large.');
+        let value;
+        try {
+            value = await body(request);
+        }
+        catch (error) {
+            return reject(error instanceof Error && error.message === 'too-large' ? 413 : 400, 'invalid-body', 'Send a valid JSON request within the message limit.');
+        }
+        if (!valid(value))
+            return reject(400, 'invalid-request', 'Choose a supported operation and its arguments.');
+        input = value;
+    }
+    else
+        return reject(405, 'method-not-allowed', 'Use GET or POST.');
+    if (!options.revalidate(request, actor))
+        return reject(401, 'unauthenticated', 'Sign in to continue.');
+    try {
+        const result = await options.execute(actor, input);
+        send(response, result.ok ? 200 : /forbidden|access|unauthor|member/.test(result.code) ? 403 : 409, result);
+    }
+    catch {
+        send(response, 502, failure('delivery-unconfirmed', 'The response could not be confirmed. Check saved messages before sending again.'));
+    }
+    return true;
+}

package/dist/team-leads.d.ts

@@ -0,0 +1,81 @@
+import type { Store } from './store.js';
+import type { TeamActor, TeamConversation, TeamLead, TeamRequest, TeamResponse, TeamRole, TeamSnapshot } from './team-contract.js';
+export type TeamAccess = {
+    conversation: TeamConversation;
+    lead: TeamLead;
+    role: TeamRole;
+};
+export type TeamClaim = {
+    conversationId: string;
+    leadId: string;
+    threadId: number;
+    messageId: number;
+    messageRevision: number;
+    generation: number;
+    runner: string;
+    actor: TeamActor;
+    text: string;
+    projects: string[];
+    instructions: string;
+    requestId: string;
+};
+/** One central database owns audiences and queued turns. No model or provider calls here. */
+export declare class TeamLeads {
+    readonly store: Store;
+    readonly enrolled: () => readonly string[];
+    constructor(store: Store, enrolled: () => readonly string[]);
+    private get db();
+    private account;
+    private leadRow;
+    private leadProjects;
+    private leadOf;
+    private leadAccess;
+    private projects;
+    private conversationOf;
+    access(actor: TeamActor, conversationId: string, required?: TeamRole): TeamAccess;
+    private event;
+    /** Permission recheck and a small indexed cursor query; it never rebuilds chat history. */
+    cursor(actor: TeamActor, conversationId?: string): number | null;
+    snapshot(actor: TeamActor, conversationId?: string, leadId?: string): TeamSnapshot;
+    execute(actor: TeamActor, request: TeamRequest, now?: Date): TeamResponse;
+    private perform;
+    private revokeMemberSessions;
+    private memberRevisions;
+    private authorStillAllowed;
+    claimNext(runner: string, now?: Date, eligible?: (candidate: {
+        actor: TeamActor;
+        conversationId: string;
+        threadId: number;
+        messageId: number;
+    }) => boolean): TeamClaim | null;
+    private claimed;
+    current(claim: TeamClaim): boolean;
+    bindTurn(claim: TeamClaim, turnId: number): boolean;
+    finish(claim: TeamClaim, result: {
+        status: 'answered' | 'failed' | 'uncertain' | 'cancelled';
+        text?: string;
+        error?: string;
+        turnId?: number;
+    }, now?: Date): boolean;
+    /** A pre-admission refusal saves a waiting reason. Admitted work is never requeued. */
+    defer(claim: TeamClaim, error: string, now?: Date): boolean;
+    /** Reconcile only recorded terminal receipts; never infer success from time or rerun a turn. */
+    reconcileFinished(now?: Date): number;
+    deliveryUncertain(turnId: number): boolean;
+    activeRunners(): string[];
+    /** Called only after the runtime proves this runner has stopped. Never repeats work. */
+    recover(runner: string, now?: Date): number;
+    followGrants(): {
+        actor: TeamActor;
+        conversation: TeamConversation;
+        lead: TeamLead;
+    }[];
+    taskOwner(taskId: string): {
+        leadId: string;
+        revision: number;
+        conversationId: string | null;
+    } | null;
+    /** Attach newly filed work in its original admission transaction. Never steals an existing owner. */
+    recordTaskOwner(taskId: string, leadId: string, conversationId: string | null, actor: TeamActor, now?: Date): boolean;
+    private transfer;
+}