@koalaauto/agentchannel 0.0.0-stage → 3.0.0-rc.1

package/dist/src/client.d.ts

@@ -0,0 +1,520 @@
+import type { Config } from './config.js';
+import { type Attachment, type StorageConfig, type TaskFile } from './attachments.js';
+export type TaskStatus = 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled';
+export declare const TERMINAL: readonly TaskStatus[];
+export declare function isTerminal(s: string | undefined): boolean;
+export type MessageKind = 'question' | 'answer' | 'decision_request' | 'decision' | 'progress' | 'result' | 'note';
+export interface Agent {
+    id: string;
+    name: string;
+    owner?: string;
+    owner_name?: string;
+    runtime?: string;
+    description?: string;
+    perm_level?: string;
+    budget_usd?: number;
+    spent_usd?: number;
+    active?: boolean;
+    last_seen?: string;
+    /** P2: domains the agent's sandbox may reach ("*" = any; admin-only). */
+    net_allow?: string[];
+}
+export interface Task {
+    id: string;
+    title: string;
+    priority?: string;
+    purpose?: string;
+    money?: string;
+    status: TaskStatus;
+    from_agent?: string;
+    to_agent?: string;
+    owner_user?: string;
+    handoff?: string;
+    handoff_version?: number;
+    waiting_on?: string;
+    depends_on?: string[];
+    cost_usd?: number;
+    links?: Record<string, unknown> | null;
+    run_id?: string;
+    /** P1: who holds the claim: a runner, or a person's interactive agent. */
+    claim_mode?: '' | 'runner' | 'interactive';
+    /** P6: the one question this task must answer. */
+    key_question?: string;
+    result?: string;
+    created?: string;
+    updated?: string;
+    /** §19: human-friendly number ("T-128" = ref) and permalink. */
+    seq?: number;
+    ref?: string;
+    url?: string;
+    /** §16: the task's channel. */
+    channel?: string;
+    channel_name?: string;
+    /** Optional expansions some routes add. */
+    from_agent_name?: string;
+    to_agent_name?: string;
+    [k: string]: unknown;
+}
+export interface Message {
+    id: string;
+    task: string;
+    author_type?: 'agent' | 'human' | 'system';
+    author_agent?: string;
+    author_user?: string;
+    kind: MessageKind | string;
+    body: string;
+    to_agent?: string;
+    to_user?: string;
+    reply_to?: string;
+    evidence?: string;
+    resolved?: boolean;
+    created?: string;
+    [k: string]: unknown;
+}
+export interface HandoffVersion {
+    version: number;
+    body: string;
+    change_note?: string;
+    author_agent?: string;
+    created?: string;
+    attachments?: Attachment[];
+}
+export interface TaskBundle {
+    task: Task;
+    handoff: string;
+    messages: Message[];
+    history: HandoffVersion[];
+    /** Attachments of the current handoff version. */
+    handoffAttachments?: Attachment[];
+    /** §21-revised: the hub's wiki context for this task's worker prompt (claim / get as the worker). */
+    wiki?: WikiContext | null;
+}
+/** §21-revised: what the hub picked from the team wiki for a worker prompt (≤ ~1k tokens). */
+export interface WikiContext {
+    budget_chars?: number;
+    decisions: {
+        id: string;
+        text: string;
+        decider?: string;
+        as_of?: string;
+        url?: string;
+        human_confirmed?: boolean;
+        use?: string;
+    }[];
+    figures: {
+        topic: string;
+        metric: string;
+        value: string;
+        unit?: string;
+        env?: string;
+        as_of: string;
+        source: string;
+        stale?: boolean;
+        use?: string;
+    }[];
+    lessons: {
+        page: string;
+        text: string;
+        stale?: boolean;
+        use?: string;
+    }[];
+    overview?: string[];
+    used_chars?: number;
+    pages: {
+        slug: string;
+        title: string;
+        url?: string;
+    }[];
+    truncated?: boolean;
+    /** Values Memory marks superseded (never injected; used to redact them from channel posts). */
+    superseded?: {
+        topic?: string;
+        metric: string;
+        value: string;
+        unit?: string;
+        env?: string;
+    }[];
+}
+export interface ClaimResult extends TaskBundle {
+    /** Empty for interactive claims (no spawned agent). */
+    run_token: string;
+}
+export type ClaimMode = 'runner' | 'interactive';
+export interface Inbox {
+    tasks_to_me: Task[];
+    questions_to_me: Message[];
+    answers_to_me: Message[];
+    decisions_for_me: Message[];
+    /** Human notes on tasks I work (author_type human), addressed to me. */
+    notes_for_me: Message[];
+    /** §16: open @mentions of me in channel posts; each wakes a read-only mention run. */
+    mentions_for_me: MentionItem[];
+    updates_on_my_tasks: unknown[];
+    server_time: string;
+}
+/** §16: a channel post or thread reply. */
+export interface Post {
+    id: string;
+    url?: string;
+    channel: string;
+    channel_name?: string;
+    kind: 'post' | 'task' | 'system' | string;
+    parent?: string;
+    author_type?: 'agent' | 'human' | 'system';
+    author_name?: string;
+    body: string;
+    evidence?: string;
+    escalated?: boolean;
+    mentions?: string[];
+    task?: string;
+    task_info?: Record<string, unknown> | null;
+    reply_count?: number;
+    attachments?: Attachment[];
+    created?: string;
+    [k: string]: unknown;
+}
+export interface Channel {
+    id: string;
+    name: string;
+    description?: string;
+    archived?: boolean;
+    post_count?: number;
+    last_post_at?: string;
+    url?: string;
+}
+export interface Thread {
+    post: Post;
+    replies: Post[];
+    focus?: string;
+}
+export interface MentionItem {
+    mention: {
+        id: string;
+        post: string;
+        thread: string;
+        status: string;
+        by: string;
+        by_type: 'agent' | 'human';
+        created?: string;
+    };
+    post: Post;
+    thread: Post;
+    channel_name: string;
+}
+export interface MentionRun extends MentionItem {
+    replies: Post[];
+    recent: Post[];
+    run_token: string;
+}
+export interface SearchResult {
+    type: 'post' | 'task' | 'message' | 'handoff';
+    id: string;
+    url: string;
+    snippet: string;
+    channel_name?: string;
+    author_name?: string;
+    task_ref?: string;
+    task_title?: string;
+    created?: string;
+    [k: string]: unknown;
+}
+export interface SendTaskInput {
+    to: string;
+    title: string;
+    priority: string;
+    purpose: string;
+    money: string;
+    handoff: string;
+    key_question?: string;
+    depends_on?: string[];
+    links?: Record<string, unknown>;
+    /** §16: channel name; default = the channel named like links.repo, else #general. */
+    channel?: string;
+}
+/** Header fields the sender may change after send. */
+export interface TaskHeaderPatch {
+    priority?: string;
+    purpose?: string;
+    money?: string;
+    key_question?: string;
+}
+/** A sender-chosen extra repo (read-only for the worker). */
+export interface LinkRepo {
+    repo: string;
+    base?: string;
+}
+/** Parse `name` or `name@base` (CLI `--read-repo`). */
+export declare function parseLinkRepo(v: string): LinkRepo;
+export interface PostMessageInput {
+    kind: MessageKind | string;
+    body: string;
+    to?: string;
+    /** Round 5: a decision request for a named person (user id, email or name; a member of the task's channel). */
+    to_user?: string;
+    evidence?: string;
+    reply_to?: string;
+    /** Tag, e.g. 'budget' for the runner's budget decision_request (§14.6). */
+    topic?: string;
+    /** A structured decision request: one question, 2–3 options (recommended first). */
+    question?: string;
+    options?: DecisionOption[];
+    recommended?: number;
+}
+export interface DecisionOption {
+    label: string;
+    detail?: string;
+    money?: string;
+}
+export declare class HubError extends Error {
+    status: number;
+    code?: string | undefined;
+    body?: unknown | undefined;
+    constructor(status: number, message: string, code?: string | undefined, body?: unknown | undefined);
+}
+/** A one-time login link: open `<hub><path>` (the token is in the URL fragment). */
+export interface LoginLink {
+    token: string;
+    path: string;
+    url: string;
+    expires_at: string;
+}
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface ClientOptions {
+    hub: string;
+    /** Agent key (ach_sk_...), run token (ach_rt_...) or a PocketBase user token. */
+    token?: string;
+    cfId?: string;
+    cfSecret?: string;
+    fetch?: FetchLike;
+}
+/** Round 2: human-facing CLI text in Chinese when LANG/LC_ALL starts with zh. */
+export declare function isZh(env: NodeJS.ProcessEnv): boolean;
+/** Picks the bearer: run token (spawned agent) beats agent key. */
+export declare function clientFromConfig(cfg: Config, opts?: {
+    admin?: boolean;
+    fetch?: FetchLike;
+}): Client;
+/** Accept either `{task, handoff, messages, history}` or a bare task record. */
+export declare function normalizeBundle(raw: any): TaskBundle;
+export declare class Client {
+    readonly hub: string;
+    private token?;
+    private cfId?;
+    private cfSecret?;
+    private fetchFn;
+    constructor(o: ClientOptions);
+    headers(json?: boolean): Record<string, string>;
+    /** `files`: local paths (already checked by resolveAttachments) sent as multipart with the JSON in field "json". */
+    request<T = any>(method: string, path: string, body?: unknown, files?: string[]): Promise<T>;
+    private storageCfg?;
+    /** GET /storage/config once per client (null on hubs without it). */
+    storageConfig(): Promise<StorageConfig | null>;
+    /**
+     * §20 v1.1: https entries become link references; media files over the hub's
+     * direct-upload threshold go straight to its bucket (presign, PUT, complete)
+     * and become upload references. The rest is sent as multipart, as before.
+     */
+    private splitAttachments;
+    /** Upload one file directly to the hub's bucket; returns the reference to attach ({upload}). */
+    directUpload(file: string, target: string): Promise<{
+        upload: string;
+    }>;
+    /** Avatars: send one image as multipart field "file" (plus plain fields). */
+    sendImage<T = any>(method: string, path: string, bytes: Uint8Array, filename: string, fields?: Record<string, string>): Promise<T>;
+    private ach;
+    /** All attachments on a task (handoff versions and messages), with hub download URLs. */
+    taskFiles(taskId: string): Promise<TaskFile[]>;
+    /** Download one attachment into `dir`; returns the local path. */
+    download(a: Attachment, dir: string): Promise<string>;
+    me(): Promise<Agent>;
+    agents(): Promise<Agent[]>;
+    sendTask(input: SendTaskInput, files?: string[]): Promise<Task>;
+    /** Propose a recurring task (runs after the owner approves). */
+    proposeSchedule(input: Record<string, unknown>): Promise<any>;
+    schedules(): Promise<any[]>;
+    scheduleAction(id: string, action: 'pause' | 'resume'): Promise<any>;
+    removeSchedule(id: string): Promise<any>;
+    /** New handoff body (+ optional header fields, same version). Sender's agent key only. */
+    updateHandoff(taskId: string, body: string, change_note: string, header?: TaskHeaderPatch, files?: string[]): Promise<any>;
+    /** Header fields only (priority, purpose, money, key_question). Sender's agent key only. */
+    updateHeader(taskId: string, header: TaskHeaderPatch, change_note?: string): Promise<any>;
+    getTask(taskId: string): Promise<TaskBundle>;
+    claim(taskId: string, run_id: string, mode?: ClaimMode): Promise<ClaimResult>;
+    /** Mint an answer-mode run token for a question addressed to me (§14.2). */
+    answerRun(taskId: string, question_id: string, run_id: string): Promise<{
+        run_token: string;
+        [k: string]: unknown;
+    }>;
+    postMessage(taskId: string, m: PostMessageInput, files?: string[]): Promise<Message>;
+    /** With an agent key the hub requires the task's current run_id (C3); run tokens carry their own. */
+    complete(taskId: string, result: string, run_id?: string, files?: string[], handoff_version?: number): Promise<any>;
+    fail(taskId: string, reason: string, run_id?: string): Promise<any>;
+    /** §23: a grantee agent answers the part of a request its grant covers. */
+    grantDecide(taskId: string, message_id: string, option: number, grant: string): Promise<any>;
+    createGrant(input: {
+        agent?: string;
+        person?: string;
+        task?: string;
+        channel?: string;
+        cap?: number;
+        until?: string;
+        note?: string;
+        requester?: string;
+    }): Promise<any>;
+    listGrants(): Promise<{
+        given: any[];
+        received: any[];
+    }>;
+    revokeGrant(id: string): Promise<any>;
+    cancel(taskId: string, reason: string): Promise<any>;
+    /** The total size of a work prompt (Memory trial metrics). */
+    promptSize(taskId: string, run_id: string, chars: number, parts?: Record<string, number>): Promise<any>;
+    usage(taskId: string, run_id: string, cost_usd: number, estimated: boolean): Promise<any>;
+    /** 409 when the run lost the task. Carries a fresh `run_token` when the old one is near expiry (C5). */
+    heartbeat(taskId: string, run_id: string): Promise<{
+        ok: boolean;
+        status: string;
+        run_token?: string;
+    }>;
+    /** Revoke the answer token(s) of a finished answer run (C4). */
+    endRun(taskId: string, run_id: string): Promise<any>;
+    inbox(): Promise<Inbox>;
+    channels(all?: boolean): Promise<Channel[]>;
+    channelPosts(channel: string, o?: {
+        since?: string;
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        channel: Channel;
+        posts: Post[];
+    }>;
+    post(channel: string, body: string, files?: string[], o?: {
+        announce?: boolean;
+    }): Promise<Post>;
+    reply(postId: string, body: string, o?: {
+        evidence?: string;
+        escalate?: boolean;
+    }, files?: string[]): Promise<Post>;
+    thread(postId: string): Promise<Thread>;
+    search(q: string, o?: {
+        channel?: string;
+        author?: string;
+        limit?: number;
+    }): Promise<{
+        query: string;
+        mode: string;
+        results: SearchResult[];
+    }>;
+    /** Take an @mention: a read-only "mention" run token for its thread. */
+    mentionRun(mentionId: string, run_id: string): Promise<MentionRun>;
+    mentionEnd(mentionId: string, run_id: string): Promise<any>;
+    mentionUsage(mentionId: string, run_id: string, cost_usd: number, estimated: boolean): Promise<any>;
+    agentProfile(name: string): Promise<any>;
+    /** `ach remember`: a fact or lesson with its source (hub permalink or GitHub URL); toTeam promotes it to the team overview. */
+    remember(text: string, source: string, o?: {
+        channel?: string;
+        topic?: string;
+        toTeam?: boolean;
+    }): Promise<any>;
+    /** `ach decide-draft`: ask the person (a decision request); their reply records the decision. */
+    decideDraft(input: {
+        text: string;
+        source: string;
+        by?: string;
+        channel?: string;
+        topic?: string;
+        task?: string;
+        scope?: string;
+    }): Promise<any>;
+    wikiIndex(channel?: string): Promise<any>;
+    wikiPage(slug: string): Promise<any>;
+    wikiSearch(q: string, limit?: number): Promise<{
+        query: string;
+        results: any[];
+    }>;
+    wikiExport(channel?: string): Promise<{
+        files: {
+            name: string;
+            slug: string;
+            version: number;
+            content: string;
+        }[];
+        template: string;
+    }>;
+    wikiPush(input: {
+        pages: unknown[];
+        figures?: unknown[];
+        note: string;
+    }): Promise<{
+        held?: boolean;
+        id?: string;
+        conflicts?: {
+            reason: string;
+        }[];
+        message?: string;
+        pages: {
+            slug: string;
+            version: number;
+            note?: string;
+        }[];
+        figures: unknown[];
+        warnings?: {
+            slug: string;
+            line: number;
+            problem: string;
+            text: string;
+        }[];
+    }>;
+    wikiSeed(): Promise<any>;
+    /** A bounded Memory summary for an interactive session (MCP instructions, SessionStart hook). */
+    memoryBrief(o?: {
+        channel?: string;
+        task?: string;
+    }): Promise<{
+        channel: string;
+        text: string;
+        chars: number;
+    }>;
+    decide(taskId: string, message_id: string, decision: string, files?: string[]): Promise<any>;
+    /** A human note on a task (user token; admins and the owners of either agent). */
+    note(taskId: string, body: string, files?: string[]): Promise<any>;
+    panel(): Promise<any>;
+    /** §15: a person (email optional) plus a one-time join link (24 h). No password. */
+    adminCreateUser(input: {
+        email?: string;
+        name: string;
+        is_admin?: boolean;
+    }): Promise<LoginLink & {
+        user: any;
+    }>;
+    adminListUsers(): Promise<any[]>;
+    /** §15: a fresh one-time login link (24 h) for a person's new device. */
+    adminUserLoginLink(ref: string): Promise<LoginLink & {
+        user: any;
+    }>;
+    adminPatchUser(ref: string, patch: Record<string, unknown>): Promise<any>;
+    /** §15 `ach open`: the agent key mints a 60 s single-use login link for its owner. */
+    loginLink(): Promise<LoginLink>;
+    /** Exchange a one-time login link token for a PocketBase user session. */
+    exchangeLoginLink(token: string): Promise<{
+        token: string;
+        record: any;
+    }>;
+    /** P4/P5: the logged-in human's own profile (notify_webhook, password, name). */
+    patchMe(patch: Record<string, unknown>): Promise<any>;
+    adminCreateAgent(input: Record<string, unknown>): Promise<any>;
+    /** `cf_token`: put the hub's shared front-door token in the invites (opt-in; default false). */
+    adminRotateKey(agentId: string, o?: {
+        cf_token?: boolean;
+    }): Promise<any>;
+    adminPatchAgent(agentId: string, patch: Record<string, unknown>): Promise<any>;
+    /** PocketBase built-in password auth for humans. */
+    userLogin(email: string, password: string): Promise<{
+        token: string;
+        record: any;
+    }>;
+}
+/** Inbox message entries are `{message, task}`; flatten to the message (task id stays in `message.task`). */
+export declare function flatMsgs(v: unknown): Message[];
+/** "#general" -> "general". */
+export declare function channelRef(c: string): string;