@hasna/bridge 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+export declare const CONFIG_VERSION: 1;
+export declare const CHANNEL_KINDS: readonly ["telegram", "console", "webhook", "imessage"];
+export type ChannelKind = (typeof CHANNEL_KINDS)[number];
+export declare const AGENT_KINDS: readonly ["codewith", "claude", "aicopilot", "shell"];
+export type AgentKind = (typeof AGENT_KINDS)[number];
+export interface BaseChannelConfig {
+    id: string;
+    kind: ChannelKind;
+    label?: string;
+    enabled?: boolean;
+}
+export interface TelegramChannelConfig extends BaseChannelConfig {
+    kind: "telegram";
+    botTokenEnv?: string;
+    defaultChatId?: string;
+    allowedChatIds?: string[];
+    allowAllChats?: boolean;
+    pollTimeoutSeconds?: number;
+}
+export interface ConsoleChannelConfig extends BaseChannelConfig {
+    kind: "console";
+}
+export interface WebhookChannelConfig extends BaseChannelConfig {
+    kind: "webhook";
+    secretEnv?: string;
+}
+export interface IMessageChannelConfig extends BaseChannelConfig {
+    kind: "imessage";
+    account?: string;
+}
+export type ChannelConfig = TelegramChannelConfig | ConsoleChannelConfig | WebhookChannelConfig | IMessageChannelConfig;
+export interface ProfileConfig {
+    id: string;
+    agentKind: AgentKind;
+    label?: string;
+    authProfile?: string;
+    cwd?: string;
+    home?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export interface AgentConfig {
+    id: string;
+    kind: AgentKind;
+    label?: string;
+    profileId?: string;
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}
+export interface RouteMatch {
+    chatIds?: string[];
+    textRegex?: string;
+}
+export interface RouteConfig {
+    id: string;
+    fromChannel: string;
+    toAgent: string;
+    responseChannel?: string;
+    enabled?: boolean;
+    match?: RouteMatch;
+}
+export interface BridgeConfig {
+    version: typeof CONFIG_VERSION;
+    channels: Record<string, ChannelConfig>;
+    profiles: Record<string, ProfileConfig>;
+    agents: Record<string, AgentConfig>;
+    routes: RouteConfig[];
+}
+export interface BridgeMessage {
+    id: string;
+    channelId: string;
+    text: string;
+    chatId?: string;
+    from?: string;
+    receivedAt: string;
+    raw?: unknown;
+}
+export interface AgentRunInput {
+    message: BridgeMessage;
+    route: RouteConfig;
+}
+export interface AgentRunResult {
+    agentId: string;
+    command: string[];
+    cwd?: string;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+export interface RoutedMessageResult {
+    route: RouteConfig;
+    agent: AgentRunResult;
+    deliveredResponse?: boolean;
+}
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    configPath: string;
+    checks: DoctorCheck[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -0,0 +1,47 @@
+# Bridge Architecture
+
+`bridge` separates channel connectors from agent adapters.
+
+Channels own external transport details such as Telegram bot tokens, chat IDs,
+webhooks, or future iMessage transport. Agents own local execution details such
+as Codewith auth profiles, Claude profile homes, AIcopilot state roots, command
+arguments, cwd, and environment. Routes connect one channel to one agent.
+
+The package deliberately keeps Telegram-specific behavior out of Codewith,
+Claude, and AIcopilot integrations. Agent adapters receive plain text prompts
+and return stdout/stderr plus process metadata. Channel connectors decide how
+to receive and deliver messages.
+
+## Data Model
+
+- `channels`: external message transports.
+- `profiles`: reusable identity/state settings for an agent family.
+- `agents`: runnable targets, usually pointing at one profile.
+- `routes`: mapping rules from channel messages to agents.
+
+## Profile Model
+
+Codewith profiles use `authProfile` and render as `codewith --auth-profile
+<name> --cd <cwd> exec <prompt>`.
+
+Claude profiles can use `home` or custom env vars so multiple accounts do not
+share local state.
+
+AIcopilot profiles currently use cwd/env/command isolation. The target repo
+work dispatched on spark02 is expected to add or document first-class profile
+support.
+
+## Telegram
+
+The first connector uses Telegram Bot API `getUpdates` long polling and
+`sendMessage`. Production deployments should move high-volume bots to webhooks,
+but long polling is the right baseline for local agent machines and early
+testing.
+
+Telegram channels fail closed unless `allowedChatIds` are configured or
+`allowAllChats` is explicitly enabled. Channel `allowedChatIds` are enforced
+before route matching. Routes can also add narrower `match.chatIds` filters, but
+they cannot expand beyond the channel allowlist.
+
+Long-poll offsets are persisted in a private state file so process restarts do
+not replay already-seen updates and re-run agents.

package/examples/bridge.config.example.json

@@ -0,0 +1,49 @@
+{
+  "version": 1,
+  "channels": {
+    "telegram-main": {
+      "id": "telegram-main",
+      "kind": "telegram",
+      "enabled": true,
+      "botTokenEnv": "TELEGRAM_BOT_TOKEN",
+      "allowedChatIds": ["123456789"],
+      "allowAllChats": false
+    }
+  },
+  "profiles": {
+    "codewith-account001": {
+      "id": "codewith-account001",
+      "agentKind": "codewith",
+      "authProfile": "account001",
+      "cwd": "/Users/hasna"
+    },
+    "claude-account001": {
+      "id": "claude-account001",
+      "agentKind": "claude",
+      "home": "/Users/hasna/.hasna/accounts/profiles/claude/account001"
+    },
+    "aicopilot-main": {
+      "id": "aicopilot-main",
+      "agentKind": "aicopilot",
+      "cwd": "/Users/hasna"
+    }
+  },
+  "agents": {
+    "codewith": {
+      "id": "codewith",
+      "kind": "codewith",
+      "profileId": "codewith-account001"
+    }
+  },
+  "routes": [
+    {
+      "id": "telegram-codewith",
+      "fromChannel": "telegram-main",
+      "toAgent": "codewith",
+      "enabled": true,
+      "match": {
+        "chatIds": ["123456789"]
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@hasna/bridge",
+  "version": "0.1.0",
+  "description": "Agent messaging bridge for Telegram and other channels",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "bridge": "dist/cli/index.js",
+    "bridge-mcp": "dist/mcp/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun --external @modelcontextprotocol/sdk && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external @modelcontextprotocol/sdk && bun build src/index.ts --outdir dist --target bun && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "dev:cli": "bun run src/cli/index.ts",
+    "dev:mcp": "bun run src/mcp/index.ts",
+    "prepublishOnly": "bun run build",
+    "postinstall": "bun -e \"const fs=require('node:fs');const path=require('node:path');const dir=path.join(process.env.HOME||process.cwd(),'.hasna','bridge');fs.mkdirSync(dir,{recursive:true,mode:0o700});try{fs.chmodSync(dir,0o700)}catch{}\""
+  },
+  "keywords": [
+    "bridge",
+    "telegram",
+    "messaging",
+    "agents",
+    "codewith",
+    "claude",
+    "aicopilot",
+    "mcp",
+    "cli"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/bridge.git"
+  },
+  "homepage": "https://github.com/hasna/bridge",
+  "bugs": {
+    "url": "https://github.com/hasna/bridge/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "author": "Andrei Hasna <andrei@hasna.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^13.1.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.4",
+    "typescript": "^5.7.3"
+  }
+}