@gitterm/bot 0.0.0-stage → 0.1.1

package/dist/markdown.d.ts

@@ -0,0 +1,7 @@
+/** Markdown tables as monospaced code blocks, for chats that do not render tables. */
+export declare function tablesToCode(markdown: string): string;
+/**
+ * Split text into chunks of at most `limit` characters, preferring line breaks. A code block
+ * cut in two is closed at the end of one chunk and reopened at the start of the next.
+ */
+export declare function splitMessage(text: string, limit: number): string[];

package/dist/preflight.d.ts

@@ -0,0 +1,17 @@
+import { type GittermClient } from "@gitterm/sdk";
+import type { BotLogger, ModelChoice, WorkspaceOverrides } from "./types.js";
+import { type Repo } from "./workspaces.js";
+export declare const BOT_TOKEN_SCOPES: readonly ["identity:read", "workspace:read", "workspace:write", "run:read", "run:write", "integrations:read"];
+/**
+ * Everything a first mention would need, checked before the bot connects, so a misconfigured
+ * bot fails at startup with what to fix instead of in a Slack thread later. Problems that only
+ * matter for some requests (a public repository without GitHub access) are warnings.
+ */
+export declare function checkSetup(input: {
+    gitterm: GittermClient;
+    repos: Repo[];
+    connections: string[];
+    model: ModelChoice | undefined;
+    overrides: WorkspaceOverrides | undefined;
+    log: BotLogger;
+}): Promise<void>;

package/dist/prompt.d.ts

@@ -0,0 +1,26 @@
+import type { AgentQuestion } from "@gitterm/sdk";
+import type { ChatFile, ChatMessage, HistoryMessage } from "./types.js";
+export declare const isForwardableImage: (file: ChatFile) => boolean;
+export type BuiltPrompt = {
+    text: string;
+    images: ChatFile[];
+};
+/**
+ * The run prompt: who is asking, the thread messages this session has not seen (as quoted
+ * context), and the request. Images are attached once, with the message that first shows them.
+ */
+export declare function buildPrompt(input: {
+    platform: string;
+    message: ChatMessage;
+    history: HistoryMessage[];
+    continued: boolean;
+}): BuiltPrompt;
+/**
+ * A typed reply as option labels: a number (`2`), numbers for multi-select (`1, 3`), or an
+ * exact label; otherwise the free-text answer when the question allows one. Null when the
+ * reply cannot answer the question.
+ */
+export declare function interpretTypedAnswer(question: AgentQuestion, text: string): string[] | null;
+/** `yes`/`allow`, `always`, or `no`/`deny` typed in reply to a permission prompt. */
+export declare function interpretPermissionReply(text: string): "once" | "always" | "reject" | null;
+export declare function agentInstructions(platform: string, extra: string | undefined): string;

package/dist/saved.d.ts

@@ -0,0 +1,10 @@
+import { type SavedBot } from "@gitterm/sdk";
+import type { BotLogger, BotOptions } from "./types.js";
+type Options = Omit<BotOptions, "adapter">;
+/**
+ * Adds the settings saved for this bot in the GitTerm dashboard (Bots), found by its API token.
+ * Routing can be overridden locally; saved authorization is an upper bound. Without saved settings,
+ * for example a token that isn't a bot's, the options come back unchanged.
+ */
+export declare function withSavedConfig(options: Options, platform: SavedBot["platform"], log?: BotLogger): Promise<Options>;
+export {};

package/dist/state.d.ts

@@ -0,0 +1,44 @@
+import type { ChatThread, ChatUser } from "./types.js";
+/** The run a thread continues from and the last chat message it has seen. */
+export type ThreadSession = {
+    /** The repository the thread works on, chosen by its first message. */
+    repo: string;
+    workspaceId: string;
+    runId: string;
+    lastMessageId: string;
+    updatedAt: number;
+};
+/** A request being worked on, so a restarted bot can pick its run up again. */
+export type InFlightRequest = {
+    /** Prevent recovery into a different platform installation after reconfiguration. */
+    scope?: string;
+    thread: ChatThread;
+    /** The status message; absent when the platform showed a native indicator instead. */
+    statusId?: string;
+    requester: ChatUser;
+    repo: string;
+    /** The sandbox (space and repository) it works in, so a restart can still guard reset. */
+    sandbox?: string;
+    /** When the server cancels the run (ms since epoch). */
+    deadline?: number;
+    /** Reply messages already posted, so a retried delivery doesn't repeat them. */
+    deliveredParts?: number;
+    /** Set once the run exists; before that a restart can only report the request as lost. */
+    run?: {
+        workspaceId: string;
+        id: string;
+    };
+};
+export type StateStore = {
+    session(threadKey: string): ThreadSession | undefined;
+    setSession(threadKey: string, session: Omit<ThreadSession, "updatedAt">): Promise<void>;
+    inFlight(): Record<string, InFlightRequest>;
+    setInFlight(threadKey: string, request: InFlightRequest | undefined): Promise<void>;
+};
+/**
+ * Holds GitTerm workspace/run ids only, never tokens, written atomically with mode 0600.
+ * It is a cache: losing it costs thread continuity, not sandboxes, which are found by metadata.
+ */
+export declare function openStateStore(file: string): Promise<StateStore>;
+/** Run operations with the same key one after another. */
+export declare function createLocks(): <T>(key: string, operation: () => Promise<T>) => Promise<T>;

package/dist/status.d.ts

@@ -0,0 +1,30 @@
+import type { ChatAdapter, ChatThread } from "./types.js";
+/**
+ * One state of a request, worded for a status message and for a native indicator, which the
+ * platform shows after the bot's name ("Acme Agent is working on it…"). An empty indicator
+ * hides it, e.g. while a prompt waits for a person.
+ */
+export type StatusText = {
+    message: string;
+    indicator: string;
+};
+export declare const WORKING: StatusText;
+export declare const WAITING_FOR_APPROVAL: StatusText;
+export declare const WAITING_FOR_ANSWER: StatusText;
+export declare const minutes: (ms: number) => number;
+export type StatusLine = {
+    /** The status message, when the platform shows no native indicator. */
+    readonly messageId: string | undefined;
+    set(status: StatusText): void;
+    /** Replace the status with a final line, e.g. an error. */
+    finish(text: string): Promise<void>;
+    /** The answer was posted; take the status away. */
+    remove(): Promise<void>;
+    stop(): void;
+};
+/**
+ * The single status of a request: the platform's native indicator when it has one, otherwise
+ * a message that is edited as the request progresses. `messageId` resumes a status message
+ * left by a previous process.
+ */
+export declare function openStatusLine(adapter: ChatAdapter, thread: ChatThread, messageId?: string): Promise<StatusLine>;

package/dist/types.d.ts

@@ -0,0 +1,215 @@
+import type { AgentPermissionRequest, AgentQuestion, GittermClient, GittermClientOptions, WorkspaceCreateInput } from "@gitterm/sdk";
+/** A conversation: the channel and the thread inside it. Every thread is one agent session. */
+export type ChatThread = {
+    channel: string;
+    thread: string;
+};
+export type ChatUser = {
+    id: string;
+    name: string;
+    /**
+     * Not a full member of the workspace (Slack guests and people from other organisations in
+     * shared channels). Guests cannot use the bot unless `allowGuests` is set.
+     */
+    guest?: boolean;
+};
+/** A file posted in the chat. Only images are forwarded to the agent; the rest are named. */
+export type ChatFile = {
+    id: string;
+    name: string;
+    mime: string;
+    size: number;
+    /** Base64 content. Called only for files the bot forwards. */
+    download(signal?: AbortSignal): Promise<string>;
+};
+export type ChatMessage = {
+    /** Platform message id (Slack `ts`, Discord snowflake). */
+    id: string;
+    thread: ChatThread;
+    author: ChatUser;
+    /** Text with the bot's own mention removed. */
+    text: string;
+    files: ChatFile[];
+    /** The bot was mentioned. Other thread replies only answer an open question. */
+    mentioned: boolean;
+    /** The thread existed before this message, so it may hold earlier context. */
+    inThread: boolean;
+    /**
+     * A one-to-one conversation with the bot. It gets its own sandbox, so the agent there can't
+     * see the sessions other people run in channels.
+     */
+    direct?: boolean;
+    /** Tenant boundary (e.g. a Discord guild). */
+    tenant?: string;
+};
+/** A message read back from a thread to give a new or continued session its context. */
+export type HistoryMessage = {
+    id: string;
+    author: ChatUser;
+    /** Written by this bot (status lines, earlier answers) or another bot. */
+    fromBot: boolean;
+    text: string;
+    files: ChatFile[];
+};
+/** Something the agent is blocked on, shown in the thread with buttons. */
+export type ChatPrompt = {
+    id: string;
+    kind: "question";
+    question: AgentQuestion;
+    /** Position among the questions the agent asked together; they are shown one at a time. */
+    index: number;
+    total: number;
+    requester: ChatUser;
+} | {
+    id: string;
+    kind: "permission";
+    request: AgentPermissionRequest;
+    requester: ChatUser;
+};
+export type ChatAnswer = {
+    kind: "question";
+    labels: string[];
+} | {
+    kind: "permission";
+    response: "once" | "always" | "reject";
+};
+/** What the engine gives an adapter to report chat activity. */
+export type ChatEvents = {
+    message(message: ChatMessage): void;
+    /**
+     * Button, menu, or dialog answer. `stale` when the prompt is no longer open, `forbidden` when
+     * this person may not use the bot; adapters tell the clicker privately.
+     */
+    answer(promptId: string, answer: ChatAnswer, by: ChatUser): "answered" | "stale" | "forbidden";
+    /** The open prompt, e.g. to build a free-text dialog for it; undefined once settled. */
+    prompt(promptId: string): ChatPrompt | undefined;
+    /** Authorization check for controls that modify pending answers without submitting them. */
+    canAnswer?(promptId: string, by: ChatUser): boolean;
+    /** Whether the bot works in this channel, so adapters do not open threads elsewhere. */
+    accepts(channel: string): boolean;
+};
+/**
+ * The chat platform half of a bot. `@gitterm/slack-bot` and `@gitterm/discord-bot` implement it;
+ * implement it yourself to put the same agent behind another chat platform.
+ */
+export interface ChatAdapter {
+    /** e.g. "slack"; tags the bot's workspaces and appears in prompts. */
+    readonly platform: string;
+    /** Human-readable platform name for prompts and instructions, e.g. "Slack". */
+    readonly displayName: string;
+    /**
+     * Connect and start reporting events. Resolves with the id of the installation (Slack team,
+     * Discord application) so two installations never share a sandbox.
+     */
+    start(events: ChatEvents): Promise<{
+        scope: string;
+    }>;
+    stop(): Promise<void>;
+    /** The thread's messages oldest first; only those after `after` when it is given. */
+    history(thread: ChatThread, after: string | undefined): Promise<HistoryMessage[]>;
+    /** Post a short plain status line; resolves with its message id. */
+    post(thread: ChatThread, text: string): Promise<string>;
+    edit(thread: ChatThread, messageId: string, text: string): Promise<void>;
+    remove(thread: ChatThread, messageId: string): Promise<void>;
+    /** The agent's answer as Markdown; the adapter converts and splits it for the platform. */
+    reply(thread: ChatThread, markdown: string, footer: string, delivery?: {
+        sent: number;
+        recordSent(sent: number): Promise<void>;
+    }): Promise<void>;
+    /** Show a prompt with controls that call `ChatEvents.answer`; resolves with its message id. */
+    ask(thread: ChatThread, prompt: ChatPrompt): Promise<string>;
+    /** Replace the prompt's controls with its outcome once it is answered or abandoned. */
+    settle(thread: ChatThread, messageId: string, prompt: ChatPrompt, outcome: string): Promise<void>;
+    /**
+     * Show the platform's native "working" indicator in the thread (e.g. "Acme Agent is working
+     * on it…"); an empty status hides it. Resolve false when the platform refuses, and the engine
+     * keeps a status message instead. Optional.
+     */
+    indicate?(thread: ChatThread, status: string): Promise<boolean>;
+    /**
+     * React to a request's message: `seen` when accepted (e.g. 👀, so people know it waits its
+     * turn), then `done` (✅) or `failed` (❌). Optional.
+     */
+    mark?(message: ChatMessage, state: "seen" | "done" | "failed"): Promise<void>;
+}
+/** A repository, optionally with a branch: `https://github.com/acme/app` or `…/app#develop`. */
+export type RepoTarget = string | {
+    url: string;
+    branch?: string;
+};
+export type ModelChoice = {
+    /** OpenCode `provider/model`, e.g. `anthropic/claude-sonnet-5-5`. */
+    id: string;
+    /** Label of a saved dashboard credential. Default: the provider's default credential. */
+    credential?: string;
+    /** An API key for this bot only; injected into the sandbox, never saved in the dashboard. */
+    apiKey?: string;
+};
+/** Workspace settings the bot does not decide itself. */
+export type WorkspaceOverrides = Omit<WorkspaceCreateInput, "repo" | "branch" | "metadata" | "name" | "agent" | "connections">;
+export type BotLogger = Pick<Console, "info" | "warn" | "error">;
+export type BotOptions = {
+    /** Stable deployment identity. Saved configurations supply the immutable bot id. */
+    botId?: string;
+    /** Authorization boundary independent of repository routing. */
+    allowedChannels?: string[];
+    /** Sharing across channels is opt-in and only appropriate for equally trusted participants. */
+    shareChannels?: boolean;
+    /** Direct-conversation sandbox lifetime. Default 7 days; resets start a new lifetime. */
+    directRetentionMs?: number;
+    /** Separate permission approvers. Defaults to the requester only. */
+    approvers?: string[];
+    /** Persistent OpenCode approvals affect future work; disabled unless explicitly enabled. */
+    allowAlways?: boolean;
+    /** Maximum accepted requests, including queued work. Default 20. */
+    maxPendingRequests?: number;
+    /** Maximum accepted requests per platform user. Default 3. */
+    maxPendingPerUser?: number;
+    adapter: ChatAdapter;
+    /** A client, or options for one. Defaults to `GITTERM_API_TOKEN` / `GITTERM_SERVER_URL`. */
+    gitterm?: GittermClient | GittermClientOptions;
+    /** Repository for every channel without its own entry in `channels`. */
+    repo?: RepoTarget;
+    /** Per-channel repositories. Without `repo` or `repos`, the bot only works in these channels. */
+    channels?: Record<string, RepoTarget>;
+    /**
+     * More repositories people can pick by naming them in a thread's first message, e.g.
+     * "@bot in acme/api, why is login slow?". A channel without a repository asks which one.
+     */
+    repos?: RepoTarget[];
+    /**
+     * Tools to attach to new sandboxes besides GitHub: connection names as shown under
+     * Integrations (`"Linear"`), integration keys (`"executor"`), or ids. GitHub access for the
+     * repository is attached automatically.
+     */
+    connections?: string[];
+    /** Environment variables for new sandboxes, e.g. test credentials. Never logged. */
+    env?: Record<string, string>;
+    /** Shell commands run in the checkout before the agent starts in a new sandbox. */
+    setup?: string[];
+    /** Platform user ids allowed to use the bot. Default: everyone in channels it can see. */
+    allowedUsers?: string[];
+    /** Let guests and people from other organisations use the bot. Default false. */
+    allowGuests?: boolean;
+    /**
+     * The model for every run, as OpenCode `provider/model`. Only that provider's credential
+     * reaches new sandboxes: its dashboard default, the saved credential labelled `credential`, or
+     * an inline `apiKey`. Without a model, sandboxes inherit no saved credentials.
+     */
+    model?: string | ModelChoice;
+    /** What the agent should know and how to behave, after the bot's own rules. New sandboxes. */
+    instructions?: string;
+    /** Provider, image, setup, OpenCode config, and other workspace settings for new sandboxes. */
+    workspace?: WorkspaceOverrides;
+    /** Thread sessions and in-flight requests. Default `.gitterm-bot/<platform>.json`. */
+    stateFile?: string;
+    /** Total time for one request, including time spent waiting for answers. Default 60 min. */
+    runTimeoutMs?: number;
+    /** How long a question or permission prompt waits for an answer. Default 30 min. */
+    inputTimeoutMs?: number;
+    logger?: BotLogger;
+};
+export type Bot = {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+};

package/dist/workspaces.d.ts

@@ -0,0 +1,63 @@
+import type { GittermClient, ModelCredential, Workspace, WorkspaceModelsInput } from "@gitterm/sdk";
+import type { StatusText } from "./status.js";
+import type { BotLogger, ModelChoice, RepoTarget, WorkspaceOverrides } from "./types.js";
+export type Repo = {
+    url: string;
+    branch: string | undefined;
+};
+/** Accepts `url`, `url#branch`, or `{ url, branch }`. */
+export declare function parseRepo(target: RepoTarget): Repo;
+export declare const repoKey: (repo: Repo) => string;
+/** `acme/app` for display; the URL itself for anything that is not a recognisable host path. */
+export declare function repoLabel(repo: Repo): string;
+/**
+ * Credentials for exactly the chosen model's provider, so a sandbox shared by a whole channel
+ * holds one model key instead of every account on the dashboard. A provider without a saved
+ * credential (free or ambient-auth models) gets none; a run that needs one then fails with the
+ * provider's authentication error, and startup warns about it.
+ */
+export declare function modelsFor(model: ModelChoice, saved: ModelCredential[]): WorkspaceModelsInput;
+/**
+ * `["github"]` when GitTerm has a GitHub connection covering the repository (the server picks
+ * it), otherwise nothing: a public repository still clones, and startup already warned.
+ */
+export declare function githubFor(gitterm: GittermClient, repo: Repo): Promise<string[]>;
+/** Channels share one sandbox per repository. */
+export declare const SHARED_SPACE = "shared";
+/** Where a message's sandbox lives: its own per direct conversation, else the shared one. */
+export declare const spaceOf: (message: {
+    direct?: boolean;
+    tenant?: string;
+    thread: {
+        channel: string;
+    };
+}, shareChannels?: boolean) => string;
+/** Sandboxes are per repository and space (shared channels, or one direct conversation). */
+export type WorkspaceManager = {
+    /** The sandbox, found by its tags or created, and running. */
+    ensure(repo: Repo, progress: (status: StatusText) => void, space?: string): Promise<Workspace>;
+    /** The sandbox, if there is one, without waking it. */
+    find(repo: Repo, space?: string): Promise<Workspace | null>;
+    /** Terminate the sandbox; the next request creates a fresh one. */
+    reset(repo: Repo, space?: string): Promise<boolean>;
+};
+export declare function createWorkspaceManager(input: {
+    gitterm: GittermClient;
+    platform: string;
+    scope: string;
+    botId?: string;
+    directRetentionMs?: number;
+    identityPolicy?: {
+        allowedUsers?: string[];
+        allowGuests?: boolean;
+        allowedChannels?: string[];
+        shareChannels?: boolean;
+    };
+    connections: string[];
+    env: Record<string, string>;
+    setup: string[];
+    model: ModelChoice | undefined;
+    instructions: string;
+    overrides: WorkspaceOverrides | undefined;
+    log: BotLogger;
+}): WorkspaceManager;

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@gitterm/bot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Chat-platform-agnostic engine for GitTerm agent bots: one sandbox per repository, one agent session per thread",
+  "keywords": [
+    "agent",
+    "bot",
+    "gitterm",
+    "opencode"
+  ],
+  "homepage": "https://gitterm.dev",
+  "license": "MIT",
+  "author": "Opeyemi Oginni",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run check-types && bun run build",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@gitterm/sdk": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.6",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}