tangram-ai 0.0.1

package/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build
+

package/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing git tag to release (example: v1.2.3)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref_name }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Pack artifact
+        run: |
+          tar -czf tangram-ai-${RELEASE_TAG}.tar.gz dist package.json package-lock.json README.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ env.RELEASE_TAG }}
+          files: |
+            tangram-ai-${{ env.RELEASE_TAG }}.tar.gz
+          generate_release_notes: true

package/README.md

@@ -0,0 +1,302 @@
+# tangram2 (MVP)
+
+Minimal Telegram chatbot built with **TypeScript + LangGraph**, with **multi-provider config** and **OpenAI Responses API** as the default provider.
+
+## Quick Start
+
+1) Install deps
+
+```bash
+npm i
+```
+
+2) Create config
+
+```bash
+mkdir -p ~/.tangram2 && cp config.example.json ~/.tangram2/config.json
+```
+
+Edit `~/.tangram2/config.json` and set:
+- `channels.telegram.token`
+- `providers.<yourProviderKey>.apiKey`
+- optionally `providers.<yourProviderKey>.baseUrl`
+
+Supported providers:
+- `openai` (Responses API)
+- `anthropic` (Messages API, supports custom `baseUrl`)
+
+3) Run
+
+```bash
+npm run gateway -- --verbose
+npm run onboard
+npm run gateway -- status
+```
+
+## Deploy & Upgrade
+
+Deployment bootstrap is part of `onboard`.
+
+```bash
+npm run onboard
+```
+
+During onboarding, the wizard can optionally install/start a user-level `systemd` service.
+
+Gateway service operations:
+
+```bash
+npm run gateway -- status
+npm run gateway -- stop
+npm run gateway -- restart
+```
+
+Upgrade and rollback:
+
+```bash
+npm run upgrade -- --dry-run
+npm run upgrade -- --version v0.0.1
+npm run rollback -- --to v0.0.1
+```
+
+Notes:
+- `upgrade` uses global npm install (`npm install -g tangram-ai@...`) and auto-restarts service
+- use `--no-restart` to skip restart
+- if `systemd --user` is unavailable, run foreground mode: `npm run gateway -- --verbose`
+
+## Release Workflow
+
+This repo includes a baseline release pipeline:
+
+- CI workflow: `.github/workflows/ci.yml`
+  - runs on push/PR
+  - executes `npm ci`, `npm run lint`, `npm test`, `npm run build`
+- Release workflow: `.github/workflows/release.yml`
+  - triggers on tag push `v*`
+  - builds project and uploads tarball asset to GitHub Release
+
+### Local release commands
+
+- Bump version only:
+
+```bash
+npm run release:patch
+npm run release:minor
+npm run release:major
+```
+
+- Prepare a full release (bump version + build + commit + tag):
+
+```bash
+npm run release:prepare:patch
+npm run release:prepare:minor
+npm run release:prepare:major
+```
+
+After `release:prepare:*` completes, push branch and tag:
+
+```bash
+git push origin master
+git push origin vX.Y.Z
+```
+
+Pushing the tag triggers GitHub Actions release creation automatically.
+
+## Onboard Wizard
+
+Run `npm run onboard` for an interactive setup that:
+- asks for provider/API/Telegram settings
+- applies developer-default permissions (shell enabled but restricted)
+- initializes `~/.tangram2` directories and baseline files
+- initializes runtime directories under `~/.tangram2/app`
+- can install/start user-level `systemd` service
+- handles existing files one by one (`overwrite` / `skip` / `backup then overwrite`)
+
+## Memory (Shared)
+
+Shared memory lives under the configured workspace directory (default: `~/.tangram2/workspace`):
+- Long-term memory: `memory/memory.md`
+- Daily notes: `memory/YYYY-MM-DD.md`
+
+Telegram commands:
+- `/memory` show memory context
+- `/remember <text>` append to today's daily memory
+- `/remember_long <text>` append to long-term memory
+
+Telegram UX behaviors:
+- bot sends `typing` action while processing
+- during tool-calling loops, progress hints may be sent as temporary `⏳ ...` updates (controlled by `channels.telegram.progressUpdates`, default `true`)
+
+## Memory Tools (LLM)
+
+The agent exposes function tools to the model (via OpenAI Responses API):
+- `memory_search` search shared memory files
+- `memory_write` append to shared memory files
+- `file_read` read local skill/content files from allowed roots
+- `file_write` write local files under allowed roots
+- `file_edit` edit files by targeted text replacement
+- `bash` execute CLI commands when `agents.defaults.shell.enabled=true`
+- `cron_schedule` schedule one-time/repeating callbacks
+- `cron_list` list scheduled callbacks
+- `cron_cancel` cancel scheduled callbacks
+
+The LangGraph workflow also runs a post-reply "memory reflection" node that can automatically summarize the latest turn into memory using a strict JSON format prompt.
+
+## Skills Metadata
+
+The runtime discovers local skills and injects a compact skills list into the model instructions, so the model can decide which skill to open/use.
+
+By default it scans:
+- `~/.tangram2/skills`
+
+You can customize via `agents.defaults.skills`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "skills": {
+        "enabled": true,
+        "roots": [
+          "~/.tangram2/skills"
+        ],
+        "maxSkills": 40,
+        "hotReload": {
+          "enabled": true,
+          "debounceMs": 800,
+          "logDiff": true
+        }
+      }
+    }
+  }
+}
+```
+
+Hot reload behavior:
+- skill directory/file changes are detected with filesystem watchers
+- reload is debounced (`hotReload.debounceMs`) to avoid noisy rapid rescans
+- updates apply globally to the next LLM execution without restarting gateway
+- when `hotReload.logDiff=true`, gateway logs added/removed/changed skills
+
+`file_read` / `file_write` / `file_edit` are path-restricted to these resolved skill roots.
+
+## Shell Tool (Optional)
+
+Enable shell execution only when needed:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "shell": {
+        "enabled": true,
+        "fullAccess": false,
+        "roots": ["~/.tangram2"],
+        "defaultCwd": "~/.tangram2/workspace",
+        "timeoutMs": 120000,
+        "maxOutputChars": 12000
+      }
+    }
+  }
+}
+```
+
+When enabled, the model can call a `bash` tool with argv form commands (e.g. `['bash','-lc','ls -la']`), constrained to allowed roots.
+
+Set `shell.fullAccess=true` to disable cwd root restrictions and allow any local path.
+
+## Heartbeat (Optional)
+
+Heartbeat periodically reads `HEARTBEAT.md` and triggers a model run with that content.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "heartbeat": {
+        "enabled": true,
+        "intervalSeconds": 300,
+        "filePath": "~/.tangram2/workspace/HEARTBEAT.md",
+        "threadId": "heartbeat"
+      }
+    }
+  }
+}
+```
+
+## Cron Scheduler
+
+Cron scheduler runs due tasks and sends their payload to the model at the scheduled time.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "cron": {
+        "enabled": true,
+        "tickSeconds": 15,
+        "storePath": "~/.tangram2/workspace/cron-tasks.json",
+        "defaultThreadId": "cron"
+      }
+    }
+  }
+}
+```
+
+Model-facing cron tools:
+- `cron_schedule` set run time, repeat mode, and `callbackPrompt` (sent to model when due, not directly to user)
+- `cron_schedule_local` set local timezone schedules (e.g. daily 09:00 Asia/Shanghai) and `callbackPrompt`
+- `cron_list` inspect pending tasks
+- `cron_cancel` remove a task by id
+
+Compatibility note:
+- old `message` field is still accepted for backward compatibility, but `callbackPrompt` is recommended
+
+## Config
+
+This project supports **multiple provider instances**. Example:
+
+```json
+{
+  "providers": {
+    "openai": {
+      "type": "openai",
+      "apiKey": "sk-...",
+      "baseUrl": "https://api.openai.com/v1",
+      "defaultModel": "gpt-4.1-mini"
+    },
+    "anthropic": {
+      "type": "anthropic",
+      "apiKey": "sk-ant-...",
+      "baseUrl": "https://api.anthropic.com",
+      "defaultModel": "claude-3-5-sonnet-latest"
+    },
+    "local": {
+      "type": "openai",
+      "apiKey": "dummy",
+      "baseUrl": "http://localhost:8000/v1",
+      "defaultModel": "meta-llama/Llama-3.1-8B-Instruct"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "openai",
+      "temperature": 0.7,
+      "systemPrompt": "You are a helpful assistant."
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABCDEF...",
+      "allowFrom": []
+    }
+  }
+}
+```
+
+Config lookup order:
+- `--config <path>`
+- `TANGRAM2_CONFIG`
+- `~/.tangram2/config.json`
+- `./config.json` (legacy fallback)

package/TODO.md

@@ -0,0 +1,5 @@
+# TODO
+
+- [ ] 设计并实现 `onboard` 命令，用于初始化 `~/.tangram2`（配置、workspace、skills 等）。
+- [ ] 在设计 `onboard` 时参考 `openclaw` / `nanobot` 的初始化与引导流程，抽取适配 tangram2 的最小可用方案。
+

package/config.example.json

@@ -0,0 +1,66 @@
+{
+  "providers": {
+    "openai": {
+      "type": "openai",
+      "apiKey": "sk-...",
+      "baseUrl": "https://api.openai.com/v1",
+      "defaultModel": "gpt-4.1-mini"
+    },
+    "anthropic": {
+      "type": "anthropic",
+      "apiKey": "sk-ant-...",
+      "baseUrl": "https://api.anthropic.com",
+      "defaultModel": "claude-3-5-sonnet-latest"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "openai",
+      "workspace": "~/.tangram2/workspace",
+      "skills": {
+        "enabled": true,
+        "roots": [
+          "~/.tangram2/skills"
+        ],
+        "maxSkills": 40,
+        "hotReload": {
+          "enabled": true,
+          "debounceMs": 800,
+          "logDiff": true
+        }
+      },
+      "shell": {
+        "enabled": false,
+        "fullAccess": false,
+        "roots": [
+          "~/.tangram2"
+        ],
+        "defaultCwd": "~/.tangram2/workspace",
+        "timeoutMs": 120000,
+        "maxOutputChars": 12000
+      },
+      "heartbeat": {
+        "enabled": false,
+        "intervalSeconds": 300,
+        "filePath": "~/.tangram2/workspace/HEARTBEAT.md",
+        "threadId": "heartbeat"
+      },
+      "cron": {
+        "enabled": true,
+        "tickSeconds": 15,
+        "storePath": "~/.tangram2/workspace/cron-tasks.json",
+        "defaultThreadId": "cron"
+      },
+      "temperature": 0.7,
+      "systemPrompt": "You are a helpful assistant. Keep replies concise."
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABCDEF...",
+      "progressUpdates": true,
+      "allowFrom": []
+    }
+  }
+}

package/dist/channels/telegram.js

@@ -0,0 +1,214 @@
+import { Telegraf } from "telegraf";
+import { randomUUID } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+import { splitTelegramMessage } from "../utils/telegram.js";
+import { withKeyLock } from "../session/locks.js";
+function createTypingLoop(ctx, chatId) {
+    let stopped = false;
+    const run = async () => {
+        while (!stopped) {
+            try {
+                await ctx.telegram.sendChatAction(chatId, "typing");
+            }
+            catch {
+            }
+            await sleep(3500);
+        }
+    };
+    void run();
+    return () => {
+        stopped = true;
+    };
+}
+function resolveChatId(rawThreadId, fallbackThreadId) {
+    const aliases = new Set(["current", "current_thread", "this_thread", "this"]);
+    let effective = rawThreadId.trim();
+    if (aliases.has(effective) && fallbackThreadId) {
+        effective = fallbackThreadId;
+    }
+    if (/^-?\d+$/.test(effective)) {
+        const asNum = Number(effective);
+        if (Number.isSafeInteger(asNum)) {
+            return asNum;
+        }
+    }
+    return effective;
+}
+export async function startTelegramGateway(config, invoke, memory, logger) {
+    const tg = config.channels.telegram;
+    if (!tg?.enabled) {
+        throw new Error("Telegram channel is not enabled in config.channels.telegram.enabled");
+    }
+    if (!tg.token) {
+        throw new Error("Telegram token is required when channels.telegram.enabled=true");
+    }
+    const bot = new Telegraf(tg.token);
+    let lastSeenChatId;
+    logger?.info("Telegram gateway starting", {
+        allowFromCount: Array.isArray(tg.allowFrom) ? tg.allowFrom.length : 0,
+        progressUpdates: tg.progressUpdates !== false,
+    });
+    const replyText = async (ctx, text) => {
+        const safeText = text && text.length > 0 ? text : "(empty reply)";
+        // Use a safety margin below Telegram's hard 4096-char limit.
+        const parts = splitTelegramMessage(safeText, 3800);
+        for (const part of parts) {
+            await ctx.reply(part, { link_preview_options: { is_disabled: true } });
+        }
+    };
+    const sendToThread = async ({ threadId, text }) => {
+        const safeText = text && text.length > 0 ? text : "(empty reply)";
+        const chatId = resolveChatId(threadId, lastSeenChatId);
+        const parts = splitTelegramMessage(safeText, 3800);
+        for (const part of parts) {
+            await bot.telegram.sendMessage(chatId, part, { link_preview_options: { is_disabled: true } });
+        }
+    };
+    bot.start(async (ctx) => {
+        await replyText(ctx, "Connected. Send me a message.");
+    });
+    bot.command("memory", async (ctx) => {
+        logger?.debug("Command /memory", {
+            chatId: String(ctx.chat?.id ?? ""),
+            userId: String(ctx.from?.id ?? ""),
+        });
+        const userId = ctx.from?.id != null ? String(ctx.from.id) : "";
+        if (Array.isArray(tg.allowFrom) && tg.allowFrom.length > 0) {
+            if (!userId || !tg.allowFrom.includes(userId)) {
+                await replyText(ctx, "Not allowed.");
+                return;
+            }
+        }
+        const text = await withKeyLock("memory", async () => memory.getMemoryContext());
+        if (!text) {
+            await replyText(ctx, "(memory is empty)");
+            return;
+        }
+        // Avoid spamming too many messages if memory grows large.
+        const maxChars = 20000;
+        const trimmed = text.length > maxChars ? text.slice(-maxChars) : text;
+        const note = text.length > maxChars ? "(showing last 20000 chars)\n\n" : "";
+        await replyText(ctx, note + trimmed);
+    });
+    bot.command("remember", async (ctx) => {
+        logger?.debug("Command /remember", {
+            chatId: String(ctx.chat?.id ?? ""),
+            userId: String(ctx.from?.id ?? ""),
+        });
+        const userId = ctx.from?.id != null ? String(ctx.from.id) : "";
+        if (Array.isArray(tg.allowFrom) && tg.allowFrom.length > 0) {
+            if (!userId || !tg.allowFrom.includes(userId)) {
+                await replyText(ctx, "Not allowed.");
+                return;
+            }
+        }
+        const raw = ctx.message?.text;
+        const payload = raw?.replace(/^\/remember\s*/i, "").trim() ?? "";
+        if (!payload) {
+            await replyText(ctx, "Usage: /remember <text>");
+            return;
+        }
+        await withKeyLock("memory", async () => memory.appendToday(payload));
+        await replyText(ctx, "Saved to today's memory.");
+    });
+    bot.command("remember_long", async (ctx) => {
+        logger?.debug("Command /remember_long", {
+            chatId: String(ctx.chat?.id ?? ""),
+            userId: String(ctx.from?.id ?? ""),
+        });
+        const userId = ctx.from?.id != null ? String(ctx.from.id) : "";
+        if (Array.isArray(tg.allowFrom) && tg.allowFrom.length > 0) {
+            if (!userId || !tg.allowFrom.includes(userId)) {
+                await replyText(ctx, "Not allowed.");
+                return;
+            }
+        }
+        const raw = ctx.message?.text;
+        const payload = raw?.replace(/^\/remember_long\s*/i, "").trim() ?? "";
+        if (!payload) {
+            await replyText(ctx, "Usage: /remember_long <text>");
+            return;
+        }
+        await withKeyLock("memory", async () => memory.appendLongTerm(payload));
+        await replyText(ctx, "Saved to long-term memory.");
+    });
+    bot.on("text", async (ctx) => {
+        const chatId = String(ctx.chat.id);
+        lastSeenChatId = chatId;
+        const userId = ctx.from?.id != null ? String(ctx.from.id) : "";
+        const text = ctx.message?.text;
+        if (!text)
+            return;
+        logger?.debug("Incoming text", {
+            chatId,
+            userId,
+            length: text.length,
+        });
+        if (Array.isArray(tg.allowFrom) && tg.allowFrom.length > 0) {
+            if (!userId || !tg.allowFrom.includes(userId)) {
+                await replyText(ctx, "Not allowed.");
+                return;
+            }
+        }
+        try {
+            const stopTyping = createTypingLoop(ctx, chatId);
+            const progressThrottleMs = 1200;
+            let lastProgressAt = 0;
+            const progressEnabled = tg.progressUpdates !== false;
+            const onProgress = async (event) => {
+                if (event.kind === "tool_progress" && !progressEnabled)
+                    return;
+                const now = Date.now();
+                if (now - lastProgressAt < progressThrottleMs)
+                    return;
+                lastProgressAt = now;
+                if (event.kind === "assistant_explanation") {
+                    await replyText(ctx, `💬 ${event.message}`);
+                    return;
+                }
+                await replyText(ctx, `⏳ ${event.message}`);
+            };
+            // Prevent concurrent invokes within a chat to keep ordering and memory sane.
+            try {
+                const reply = await withKeyLock(chatId, async () => invoke({ threadId: chatId, text, onProgress }));
+                logger?.debug("Outgoing reply", { chatId, length: reply.length });
+                await replyText(ctx, reply);
+            }
+            finally {
+                stopTyping();
+            }
+        }
+        catch (err) {
+            // Avoid echoing huge payloads back to Telegram (which can recurse into the same error).
+            // Log full error locally.
+            const errorId = randomUUID().slice(0, 8);
+            // eslint-disable-next-line no-console
+            console.error(`[telegram][${errorId}]`, err);
+            logger?.error("Invoke failed", { errorId, chatId, userId, message: err?.message });
+            // User-facing error should be short and never include provider payloads.
+            const safe = `Provider error (${errorId}). Check server logs.`;
+            try {
+                await replyText(ctx, safe);
+            }
+            catch (inner) {
+                // eslint-disable-next-line no-console
+                console.error("Failed to send error message", inner);
+            }
+        }
+    });
+    void bot
+        .launch()
+        .then(() => {
+        logger?.info("Telegram bot launched");
+    })
+        .catch((err) => {
+        logger?.error("Telegram bot launch failed", {
+            message: err?.message,
+        });
+    });
+    // Graceful shutdown.
+    const stop = () => bot.stop("SIGTERM");
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    return { sendToThread };
+}