typeclaw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeon Suyeol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# TypeClaw
+
+> A TypeScript-native, Bun-powered, Docker-friendly general-purpose agent runtime.
+
+## Why?
+
+There are great agents out there. None of them were quite the shape I wanted:
+
+- **OpenClaw** — feature-rich, but heavy
+- **NanoClaw** — simple, but no plugin system
+- **PicoClaw** — fast, but Go (so plugins live outside the runtime)
+- **ZeroClaw** — light, but Rust (same problem, different ecosystem)
+- **Hermes Agent** — awesome, but Python
+
+None of that matters to most people. It matters to me. If you're like me, TypeClaw is the right choice.
+
+TypeClaw is the agent I wanted to use:
+
+- **TypeScript end to end** — agent core, plugins, channel adapters, CLI, TUI all in one language
+- **Bun-native plugins** — plugins are just TS modules; no IPC, no FFI, hot-reloadable config
+- **Docker-friendly by default** — every agent runs in its own container; the host CLI is purely a launcher
+- **Multi-channel out of the box** — Slack, Discord, TUI, websocket — all routed through one in-process stream
+- **Self-improving** — the agent observes its own work, distills it into long-term memory and reusable skills, and gets sharper over time without you writing prompts for it
+
+## Features
+
+- 🐳 **Sandboxed by default** — every agent runs in its own Docker container, with an `.env` and bind-mounted host folders
+- 🔌 **Plugin system** — plain TypeScript modules contribute tools, skills, subagents, channels, and typed config
+- 💬 **Multi-channel** — Slack, Discord, and a websocket TUI out of the box; one agent, many inboxes
+- 👥 **Group chat awareness** — knows who's in the room, distinguishes humans from bots, and stays engaged after a reply without re-mentioning
+- ⏰ **Cron** — schedule prompts or shell commands; per-job coalescing so slow jobs don't pile up
+- 📚 **Skills on demand** — markdown procedures the agent loads only when relevant; zero token cost until used
+- 🌱 **Self-improving** — bundled memory plugin observes the agent's work and consolidates it into long-term memory (see below)
+- 🧠 **Muscle memory** — repeated procedures get distilled into reusable skills that the agent writes for itself
+- 🔄 **Hot reload** — change `typeclaw.json`, `typeclaw reload` — no restart for most fields
+- 🔁 **Self-restart** — the agent can bounce its own container when it updates itself
+- 🌐 **Auto port-forward** — dev servers inside the container appear on `localhost`, even loopback-only ones
+- 🎼 **Compose** — orchestrate multiple agents across multiple folders
+
+### 🌱 Self-improving, in detail
+
+The bundled `memory` plugin turns lived experience into reusable knowledge. No manual prompt engineering. No curated example library.
+
+1. **Observe.** After every idle turn, a `memory-logger` subagent reads the transcript and appends notable fragments to `memory/yyyy-MM-dd.md`. Cheap, frequent, lossy by design.
+2. **Dream.** On a cron schedule (default 4am), a `dreaming` subagent consolidates daily streams into `MEMORY.md`, and — when it spots a procedure worth remembering — writes it as **muscle memory**: a new skill at `memory/skills/<name>/SKILL.md`.
+3. **Apply.** Tomorrow's prompt sees the updated `MEMORY.md`. Muscle-memory skills sit alongside bundled and user-installed ones, loaded on demand. Every dream is `git commit -m Dream`'d, so growth is auditable.
+
+See [`src/bundled-plugins/memory/README.md`](./src/bundled-plugins/memory/README.md) for the full contract.
+
+## Install
+
+```sh
+bun add -g typeclaw
+```
+
+Requires Bun ≥ 1.1 and Docker (or OrbStack) on the host.
+
+## Quickstart
+
+```sh
+mkdir my-agent && cd my-agent
+typeclaw init        # scaffold typeclaw.json, .env, Dockerfile, package.json
+typeclaw start       # build + run the container
+typeclaw tui         # attach a terminal UI to the running agent
+```
+
+That's it. The agent is now alive, listening on a websocket, ready to receive prompts from the TUI or any wired channel.
+
+## CLI
+
+| Command            | Purpose                                         |
+| ------------------ | ----------------------------------------------- |
+| `typeclaw init`    | Scaffold a new agent folder                     |
+| `typeclaw start`   | Build and run the container                     |
+| `typeclaw stop`    | Stop the container                              |
+| `typeclaw restart` | `stop` then `start`                             |
+| `typeclaw status`  | Show container + daemon registration state      |
+| `typeclaw logs`    | `docker logs` passthrough, `-f` to follow       |
+| `typeclaw tui`     | Attach a terminal UI over the agent's websocket |
+| `typeclaw shell`   | Open a shell inside the running container       |
+| `typeclaw reload`  | Push a live config reload to the running agent  |
+| `typeclaw compose` | Orchestrate multiple agents                     |
+
+## Configuration
+
+Agent folder layout after `init`:
+
+```
+my-agent/
+├── typeclaw.json     # main config (schema-validated)
+├── cron.json         # scheduled jobs (optional)
+├── .env              # secrets, injected via --env-file
+├── Dockerfile        # auto-managed by typeclaw, refreshed every `start`
+├── package.json      # `typeclaw` as a dependency
+├── .gitignore        # auto-managed
+├── workspace/        # agent's free-write zone (gitignored)
+├── sessions/         # JSONL session logs (gitignored, force-committed by auto-backup)
+└── memory/           # MEMORY.md + muscle-memory skills (gitignored, force-committed by dreaming)
+```
+
+`typeclaw.json` is JSON Schema–validated (see `typeclaw.schema.json`). Highlights:
+
+- `port` — preferred host port (CLI falls back to ephemeral on conflict)
+- `mounts` — host directories to expose inside the container
+- `plugins` — list of plugin module specifiers
+- `channels` — `slack-bot` / `discord-bot` config
+- `portForward` — allow/deny list for auto port forwarding (default: `*`)
+- `dockerfile` — toggles for `gh`, `python`, `tmux`, `ffmpeg`, plus `append` lines
+- `memory` — idle window and dreaming schedule for the memory plugin
+
+`Dockerfile` and `.gitignore` are owned by TypeClaw and rewritten on every `start` — edit `src/init/dockerfile.ts` and re-run `start --build` to ship template changes.
+
+## Development
+
+```sh
+git clone https://github.com/typeclaw/typeclaw
+cd typeclaw
+bun install
+bun test
+```
+
+Pre-commit checks (must all pass — no exceptions):
+
+```sh
+bun run typecheck
+bun run lint
+bun run format
+```
+
+See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy.
+
+## License
+
+MIT

package/auth.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "type": "number",
+      "const": 1
+    },
+    "llm": {
+      "default": {},
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "api_key"
+              },
+              "key": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "type",
+              "key"
+            ]
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "oauth"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "additionalProperties": {}
+          }
+        ]
+      }
+    },
+    "channels": {
+      "default": {},
+      "type": "object",
+      "properties": {},
+      "additionalProperties": {}
+    }
+  },
+  "required": [
+    "version"
+  ]
+}

package/cron.schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "jobs": {
+      "default": [],
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-zA-Z0-9_-]+$"
+              },
+              "schedule": {
+                "type": "string",
+                "minLength": 1
+              },
+              "enabled": {
+                "default": true,
+                "type": "boolean"
+              },
+              "timezone": {
+                "type": "string"
+              },
+              "kind": {
+                "type": "string",
+                "const": "prompt"
+              },
+              "prompt": {
+                "type": "string",
+                "minLength": 1
+              },
+              "subagent": {
+                "type": "string",
+                "minLength": 1
+              },
+              "payload": {}
+            },
+            "required": [
+              "id",
+              "schedule",
+              "kind",
+              "prompt"
+            ]
+          },
+          {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-zA-Z0-9_-]+$"
+              },
+              "schedule": {
+                "type": "string",
+                "minLength": 1
+              },
+              "enabled": {
+                "default": true,
+                "type": "boolean"
+              },
+              "timezone": {
+                "type": "string"
+              },
+              "kind": {
+                "type": "string",
+                "const": "exec"
+              },
+              "command": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            },
+            "required": [
+              "id",
+              "schedule",
+              "kind",
+              "command"
+            ]
+          }
+        ]
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "typeclaw",
+  "version": "0.1.0",
+  "homepage": "https://github.com/typeclaw/typeclaw#readme",
+  "bugs": {
+    "url": "https://github.com/typeclaw/typeclaw/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typeclaw/typeclaw.git"
+  },
+  "bin": {
+    "typeclaw": "src/cli/index.ts"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "typeclaw.schema.json",
+    "cron.schema.json",
+    "secrets.schema.json",
+    "auth.schema.json",
+    "!**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    "./plugin": "./src/plugin/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "check": "bun run typecheck && bun run lint && bun run format:check",
+    "test": "bun test",
+    "generate:schema": "bun run scripts/generate-schema.ts",
+    "postinstall": "bun run scripts/generate-schema.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "@mariozechner/pi-coding-agent": "^0.67.3",
+    "@mariozechner/pi-tui": "^0.67.3",
+    "@mozilla/readability": "^0.6.0",
+    "agent-messenger": "2.14.1",
+    "cheerio": "^1.2.0",
+    "citty": "^0.2.2",
+    "cron-parser": "^5.5.0",
+    "jq-wasm": "^1.1.0-jq-1.8.1",
+    "jsdom": "^29.0.2",
+    "turndown": "^7.2.4",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/jsdom": "^28.0.1",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/turndown": "^5.0.6",
+    "@types/ws": "^8.18.1",
+    "@typescript/native-preview": "^7.0.0-dev.20260416.1",
+    "oxfmt": "^0.45.0",
+    "oxlint": "^1.60.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  }
+}

package/scripts/emit-base-dockerfile.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+
+import { buildBaseDockerfile } from '../src/init/dockerfile'
+
+process.stdout.write(buildBaseDockerfile())

package/scripts/generate-schema.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env bun
+
+import { writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { z } from 'zod'
+
+import { configSchema as coreConfigSchema } from '../src/config/config'
+import { cronFileSchema } from '../src/cron/schema'
+import { buildConfigSchemaWithBundledPlugins } from '../src/run/schema-with-plugins'
+import { secretsFileSchema } from '../src/secrets/schema'
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+// auth.schema.json is the permanent compatibility alias for secrets.schema.json.
+// Pre-rename `auth.json` files (or migrated `secrets.json` files that still
+// carry the legacy `$schema` URL — `mergeLlmIntoEnvelope` preserves an
+// existing `$schema`, so the legacy pointer survives the file rename) need
+// it to resolve in editors. The alias is tiny and re-emitting it has no
+// maintenance cost, so we keep it indefinitely rather than coordinating a
+// content-rewrite migration for every old agent folder.
+const targets: Array<{ path: string; schema: z.ZodType }> = [
+  { path: join(repoRoot, 'typeclaw.schema.json'), schema: buildConfigSchemaWithBundledPlugins(coreConfigSchema) },
+  { path: join(repoRoot, 'cron.schema.json'), schema: cronFileSchema },
+  { path: join(repoRoot, 'secrets.schema.json'), schema: secretsFileSchema },
+  { path: join(repoRoot, 'auth.schema.json'), schema: secretsFileSchema },
+]
+
+for (const { path, schema } of targets) {
+  const json = z.toJSONSchema(schema, { io: 'input', reused: 'inline' })
+  await writeFile(path, `${JSON.stringify(json, null, 2)}\n`)
+  console.log(`Wrote ${path}`)
+}

package/secrets.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "type": "number",
+      "const": 1
+    },
+    "llm": {
+      "default": {},
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "api_key"
+              },
+              "key": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "type",
+              "key"
+            ]
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "oauth"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "additionalProperties": {}
+          }
+        ]
+      }
+    },
+    "channels": {
+      "default": {},
+      "type": "object",
+      "properties": {},
+      "additionalProperties": {}
+    }
+  },
+  "required": [
+    "version"
+  ]
+}

package/src/agent/auth.ts

@@ -0,0 +1,119 @@
+import { join } from 'node:path'
+
+import { AuthStorage, ModelRegistry } from '@mariozechner/pi-coding-agent'
+
+import { getConfig } from '@/config'
+import {
+  KNOWN_PROVIDERS,
+  providerForModelRef,
+  supportsApiKey,
+  supportsOAuth,
+  type KnownProviderId,
+} from '@/config/providers'
+import { createSecretsStoreForAgent } from '@/secrets'
+
+type Auth = {
+  authStorage: AuthStorage
+  modelRegistry: ModelRegistry
+}
+
+const TEST_DUMMY_API_KEY = 'test_dummy_key'
+
+// In container stage, /agent is the bind-mounted agent folder; in host stage
+// (only used by `typeclaw init` itself), it falls back to process.cwd(). The
+// host writes secrets.json at init time and the container reads + refreshes
+// it at runtime — both paths point at the same file on the host filesystem.
+function secretsJsonPath(): string {
+  return join(process.cwd(), 'secrets.json')
+}
+
+let cached: Auth | null = null
+
+export function getAuth(): Auth {
+  if (cached) return cached
+
+  const providerId = providerForModelRef(getConfig().model)
+  const provider = KNOWN_PROVIDERS[providerId]
+
+  // Bun sets NODE_ENV=test automatically under `bun test`. The dummy path
+  // bypasses both secrets.json and process.env so suites that build sessions
+  // but never hit the LLM don't need real credentials; production still
+  // hard-exits to surface misconfiguration.
+  if (process.env.NODE_ENV === 'test' && !hasAnyCredentialInEnv(provider.apiKeyEnv)) {
+    const authStorage = AuthStorage.inMemory()
+    if (supportsApiKey(provider)) {
+      authStorage.setRuntimeApiKey(provider.id, TEST_DUMMY_API_KEY)
+    }
+    const modelRegistry = ModelRegistry.create(authStorage)
+    cached = { authStorage, modelRegistry }
+    return cached
+  }
+
+  const authStorage = createSecretsStoreForAgent(secretsJsonPath())
+
+  // Persist the .env API key into secrets.json so the file is the single
+  // source of truth for credentials. Upstream pi-ai's `getEnvApiKey()` only
+  // knows about a hardcoded set of providers (anthropic, openai, etc.) and
+  // does NOT know about Fireworks, so `hasAuth("fireworks")` returns false
+  // unless a credential is materialized into AuthStorage's data map. Before
+  // this migration the code used `setRuntimeApiKey`, which papered over the
+  // gap in-memory but never wrote secrets.json — leaving `llm` empty for every
+  // downstream consumer (rotation, audit, transport over the daemon
+  // boundary) that treats the file as authoritative.
+  //
+  // Policy: never overwrite an existing OAuth credential. The user
+  // explicitly logged in at init, and an unrelated `.env` value must not
+  // silently displace it. Only write when no credential exists, or when an
+  // existing api-key value drifted from the env var (the user rotated the
+  // key in .env and expects the next boot to pick it up).
+  if (supportsApiKey(provider) && provider.apiKeyEnv) {
+    const envKey = process.env[provider.apiKeyEnv]
+    if (envKey) {
+      const existing = authStorage.get(provider.id)
+      const needsWrite = existing === undefined || (existing.type === 'api_key' && existing.key !== envKey)
+      if (needsWrite) {
+        authStorage.set(provider.id, { type: 'api_key', key: envKey })
+      }
+    }
+  }
+
+  // OAuth providers persist via `oauth-login.ts` at init time; api-key
+  // providers persist via the migration block above. By this point
+  // secrets.json is authoritative — a missing entry means the user skipped
+  // login at init, deleted the file, or never set the provider's env var.
+  if (!authStorage.hasAuth(provider.id)) {
+    console.error(missingCredentialMessage(providerId))
+    process.exit(1)
+  }
+
+  const modelRegistry = ModelRegistry.create(authStorage)
+  cached = { authStorage, modelRegistry }
+  return cached
+}
+
+export function resetAuthForTesting(): void {
+  cached = null
+}
+
+function hasAnyCredentialInEnv(apiKeyEnv: string | null): boolean {
+  return apiKeyEnv !== null && process.env[apiKeyEnv] !== undefined && process.env[apiKeyEnv] !== ''
+}
+
+function missingCredentialMessage(providerId: KnownProviderId): string {
+  const provider = KNOWN_PROVIDERS[providerId]
+  const ref = getConfig().model
+  const slash = ref.indexOf('/')
+  const modelName =
+    (provider.models as Record<string, { name: string }>)[ref.slice(slash + 1)]?.name ?? ref.slice(slash + 1)
+
+  const oauthOnly = supportsOAuth(provider) && !supportsApiKey(provider)
+  const apiKeyOnly = supportsApiKey(provider) && !supportsOAuth(provider)
+
+  if (oauthOnly) {
+    return `No credentials for ${provider.name}. Run \`typeclaw init\` and pick "OAuth" to log in to ${modelName}.`
+  }
+  if (apiKeyOnly && provider.apiKeyEnv) {
+    return `Set ${provider.apiKeyEnv} in .env to use ${modelName} via ${provider.name}.`
+  }
+  return `No credentials for ${provider.name}. Either set ${provider.apiKeyEnv ?? '<api-key-env>'} in .env or run \`typeclaw init\` and pick "OAuth".`
+}

package/src/agent/compaction.ts

@@ -0,0 +1,35 @@
+import type { KnownApi, Model } from '@mariozechner/pi-ai'
+import { SettingsManager } from '@mariozechner/pi-coding-agent'
+
+// Compaction trigger threshold expressed as a percentage of the model's
+// context window. pi-coding-agent's auto-compaction fires when
+// `contextTokens > contextWindow - reserveTokens`. To honor a percentage-
+// based intent across models with very different window sizes (200K Claude
+// vs. 1M Gemini vs. 256K Kimi), we derive `reserveTokens` per-model from
+// the model's `contextWindow`. SDK defaults (16384 reserve) are a fixed
+// number of tokens that drift in relative terms across models — at 256K
+// that's ~6% headroom (94% trigger), at 1M it's ~1.6% (98% trigger). A
+// percentage-derived reserve trips at the same fraction regardless of
+// model, which is what we actually want.
+export const COMPACTION_TRIGGER_PERCENT = 0.8
+
+// Tokens to keep in the recent window after compaction. Fixed (not a
+// percentage) because "recent context" is a property of conversation
+// shape, not model capacity — the same recent ~20K is roughly the right
+// amount of history regardless of whether the model has 200K or 1M total.
+// Mirrors pi's DEFAULT_COMPACTION_SETTINGS.keepRecentTokens.
+export const COMPACTION_KEEP_RECENT_TOKENS = 20_000
+
+export function reserveTokensForModel<TApi extends KnownApi>(model: Model<TApi>): number {
+  return Math.max(1, Math.round(model.contextWindow * (1 - COMPACTION_TRIGGER_PERCENT)))
+}
+
+export function createCompactionSettingsManager<TApi extends KnownApi>(model: Model<TApi>): SettingsManager {
+  return SettingsManager.inMemory({
+    compaction: {
+      enabled: true,
+      reserveTokens: reserveTokensForModel(model),
+      keepRecentTokens: COMPACTION_KEEP_RECENT_TOKENS,
+    },
+  })
+}