@gitterm/bot 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# @gitterm/bot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The engine behind [`@gitterm/slack-bot`](https://www.npmjs.com/package/@gitterm/slack-bot) and [`@gitterm/discord-bot`](https://www.npmjs.com/package/@gitterm/discord-bot).
+It turns chat messages into [GitTerm](https://gitterm.dev) agent runs with one opinionated model:
+
+- **One sandbox per bot, tenant, channel and repository**, tagged for safe recovery. It pauses when
+  idle and is woken by the next message.
+- **One OpenCode session per chat thread.** Follow-ups continue the session; messages posted in
+  between travel along as quoted context; images are attached once.
+- **Questions and tool approvals become chat prompts** with buttons and typed replies.
+- **Restarts reattach** to runs that were in flight.
+
+Use it directly to put the same agent behind another chat platform. You write a `ChatAdapter`;
+the engine owns sandboxes, sessions, runs, prompts, and recovery.
+
+```ts
+import { createBot, type ChatAdapter } from "@gitterm/bot";
+
+const adapter: ChatAdapter = {
+  platform: "matrix",
+  displayName: "Matrix",
+  async start(events) {
+    // Connect, then report every message in a thread with events.message({...}).
+    // Buttons call events.answer(promptId, answer, user).
+    return { scope: "<installation id>" };
+  },
+  async stop() {},
+  async history(thread, after) {
+    /* the thread's messages, oldest first */ return [];
+  },
+  async post(thread, text) {
+    /* post a status line, return its id */ return "id";
+  },
+  async edit(thread, messageId, text) {},
+  async remove(thread, messageId) {},
+  async reply(thread, markdown, footer) {
+    /* split with splitMessage() */
+  },
+  async ask(thread, prompt) {
+    /* render a question or permission prompt */ return "id";
+  },
+  async settle(thread, messageId, prompt, outcome) {
+    /* remove its controls */
+  },
+};
+
+await createBot({ adapter, repo: "https://github.com/acme/app" }).start();
+```
+
+`createBot` takes the same options as the platform bots (`repo`, `channels`, `connections`,
+`model`, `instructions`, `workspace`, `stateFile`, timeouts); see the
+[Slack bot README](https://www.npmjs.com/package/@gitterm/slack-bot#configuration). `splitMessage`, `tablesToCode`, and
+`interpretTypedAnswer` are exported for adapters.
+
+The engine reports a message to the agent only when `mentioned` is true. Other thread replies
+answer an open prompt when they come from the person who asked. Every message id must be unique
+within its thread, and `history(thread, after)` must return only messages after `after`.
+
+Two adapter methods are optional: `mark(message, state)` reacts to a request (👀, then ✅ or ❌), and
+`indicate(thread, status)` shows a native "is working…" indicator instead of a status message
+(`""` hides it; resolve `false` to fall back to status messages).
+
+## Security and operations
+
+- **A saved bot's token is the bot, not you.** It reaches only the workspaces it created and only
+  its saved repository, model and tools. Call `withSavedConfig()` before `createBot()`: if the
+  saved settings can't be loaded, startup fails, and local settings can narrow its users and
+  channels but never widen them.
+- **Sandboxes are per bot, channel and repository.** Private and public channels, and Discord
+  servers, never share one; `shareChannels: true` opts trusted channels into one. A direct
+  conversation gets its own, terminated after seven days (`directRetentionMs`).
+- **Nothing personal is inherited.** Bot sandboxes get none of your saved environment variables or
+  agent config, and only the chosen model's credential.
+- **Settings changes need `reset`.** A sandbox made with other settings is kept (it may hold work)
+  until someone runs `reset` in that channel. Reset doesn't revoke credentials it already received;
+  revoke those upstream.
+- **Threads run side by side** in their sandbox, each its own session. The agent is told to check
+  for other sessions' work before switching branches.
+- **`stop` and the deadline cover the whole request**, from waking the sandbox to the run itself,
+  and the server cancels a run at its deadline even if the bot is gone. Approvals go to the
+  requester unless you set `approvers`; "always allow" is off unless `allowAlways` is on.
+- **One process per saved bot.** A second one waits for the first to stop (up to 90 seconds after a
+  crash); a process that loses its claim stops with exit code 1. Keep the state file on persistent
+  storage so restarts pick up runs in flight.

package/dist/bot.d.ts

@@ -0,0 +1,6 @@
+import type { Bot, BotOptions } from "./types.js";
+/**
+ * A chat bot backed by GitTerm sandboxes: one sandbox per repository that pauses when idle and
+ * wakes on the next message, and one OpenCode session per chat thread.
+ */
+export declare function createBot(options: BotOptions): Bot;

package/dist/download.d.ts

@@ -0,0 +1,7 @@
+/** Stream platform attachments with a deadline and actual-byte bound; never forward credentials
+ * to redirects or to a URL outside the platform's documented file hosts. */
+export declare function downloadImage(url: string, options: {
+    hosts: string[];
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}): Promise<string>;

package/dist/env.d.ts

@@ -0,0 +1,21 @@
+import type { BotOptions } from "./types.js";
+type Env = Record<string, string | undefined>;
+/**
+ * Bot settings from the environment, shared by the Slack and Discord command lines. GitTerm
+ * credentials are read by the SDK itself (`GITTERM_API_TOKEN`, `GITTERM_SERVER_URL`, or the
+ * `gitterm login` config).
+ */
+export declare function botOptionsFromEnv(env?: Env): Omit<BotOptions, "adapter">;
+/**
+ * The shared command-line entry: loads `.env` from the working directory and returns the bot
+ * options. `--repo`, `--model`, and `--instructions-file` override their environment variables.
+ */
+export declare function cliOptions(argv?: string[]): {
+    command: string | undefined;
+    options: Omit<BotOptions, "adapter">;
+};
+/** The environment variables every bot command line reads, for its usage text. */
+export declare const BOT_ENV_HELP = "  Saved policy loads at startup; local settings cannot broaden its users, guests, or channels.\n\n  GITTERM_API_TOKEN               The bot's GitTerm token (dashboard \u2192 Bots creates one)\n  GITTERM_SERVER_URL              Self-hosted GitTerm API URL (default: hosted)\n  GITTERM_BOT_REPO                Repository for every channel: https://github.com/acme/app[#branch]\n  GITTERM_BOT_REPOS               More repositories people can name in a thread: url,url\n  GITTERM_BOT_CHANNELS            Per-channel repositories: <channel id>=<url>,\u2026\n  GITTERM_BOT_MODEL               provider/model, e.g. anthropic/claude-sonnet-5-5\n  GITTERM_BOT_MODEL_CREDENTIAL    Saved credential label (default: the provider's default)\n  GITTERM_BOT_MODEL_API_KEY       Or a model API key for this bot only\n  GITTERM_BOT_GITHUB_TOKEN        Your own GitHub token instead of a GitTerm GitHub connection\n  GITTERM_BOT_CONNECTIONS         Tools besides GitHub, by name: Linear,Sentry\n  GITTERM_BOT_ALLOWED_USERS       Only these user ids may use the bot: U012,U034\n  GITTERM_BOT_ID                  Names an unsaved bot's sandboxes (saved bots use their own id)\n  GITTERM_BOT_ALLOWED_CHANNELS    Only these channel ids, whatever the repository routing\n  GITTERM_BOT_APPROVERS           Permission approver ids (default: requester only)\n  GITTERM_BOT_ALLOW_ALWAYS        true enables persistent approvals (default: disabled)\n  GITTERM_BOT_SHARE_CHANNELS      true opts equally trusted channels into a shared sandbox\n  GITTERM_BOT_MAX_PENDING[_PER_USER] Queue bounds (defaults: 20 total, 3 per user)\n  GITTERM_BOT_ALLOW_GUESTS        true lets guests and external people use the bot\n  GITTERM_BOT_INSTRUCTIONS[_FILE] What the agent should know and how to behave\n  GITTERM_BOT_SETUP               Command run before the agent starts, e.g. \"pnpm install\"\n  GITTERM_BOT_SANDBOX_ENV_FILE    dotenv file of variables for the sandbox (test credentials)\n  GITTERM_BOT_PROVIDER            Compute provider for new sandboxes (railway, e2b, \u2026)\n  GITTERM_BOT_STATE_FILE, GITTERM_BOT_RUN_TIMEOUT_MINUTES";
+/** Whether the options name at least one repository the bot can work on. */
+export declare const hasRepository: (options: Omit<BotOptions, "adapter">) => boolean;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createBot } from "./bot.js";
+export { downloadImage } from "./download.js";
+export { withSavedConfig } from "./saved.js";
+export { BOT_ENV_HELP, botOptionsFromEnv, cliOptions, hasRepository } from "./env.js";
+export { BOT_TOKEN_SCOPES } from "./preflight.js";
+export { splitMessage, tablesToCode } from "./markdown.js";
+export { interpretTypedAnswer } from "./prompt.js";
+export type { Bot, BotLogger, BotOptions, ChatAdapter, ChatAnswer, ChatEvents, ChatFile, ChatMessage, ChatPrompt, ChatThread, ChatUser, HistoryMessage, ModelChoice, RepoTarget, WorkspaceOverrides, } from "./types.js";