typeclaw 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/cli/channel.ts

@@ -25,7 +25,7 @@ import {
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 
-import { c, done, errorLine } from './ui'
+import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
 
 const CHANNEL_LABELS: Record<ChannelKind, string> = {
   'slack-bot': 'Slack',
@@ -834,50 +834,7 @@ async function promptDiscordToken(): Promise<string> {
 }
 
 async function promptSlackTokens(): Promise<{ bot: string; app: string }> {
-  note(
-    [
-      '1. https://api.slack.com/apps → Create New App → From a manifest.',
-      '   Pick your workspace, then paste this JSON manifest:',
-      '',
-      '   {',
-      '     "display_information": { "name": "TypeClaw" },',
-      '     "features": {',
-      '       "bot_user": { "display_name": "TypeClaw", "always_online": true }',
-      '     },',
-      '     "oauth_config": {',
-      '       "scopes": {',
-      '         "bot": [',
-      '           "app_mentions:read", "chat:write", "users:read", "files:read",',
-      '           "channels:history", "channels:read",',
-      '           "groups:history",   "groups:read",',
-      '           "im:history",       "im:read",',
-      '           "mpim:history",     "mpim:read"',
-      '         ]',
-      '       }',
-      '     },',
-      '     "settings": {',
-      '       "event_subscriptions": {',
-      '         "bot_events": [',
-      '           "app_mention",',
-      '           "message.channels", "message.groups",',
-      '           "message.im",       "message.mpim"',
-      '         ]',
-      '       },',
-      '       "socket_mode_enabled": true',
-      '     }',
-      '   }',
-      '',
-      '2. Install to Workspace, then OAuth & Permissions →',
-      '   copy the Bot User OAuth Token (xoxb-...).',
-      '3. Basic Information → App-Level Tokens → Generate Token and',
-      '   Scopes, add the connections:write scope, and copy the',
-      '   token (xapp-...). Socket Mode needs this; the manifest',
-      '   cannot grant it.',
-      '4. Invite the bot to any private channel or DM you want it in:',
-      '   /invite @TypeClaw',
-    ].join('\n'),
-    'Get a Slack bot',
-  )
+  printSlackAppManifestSetup()
   const bot = await promptSlackBotToken()
   note(
     [

package/src/cli/init.ts

@@ -32,7 +32,7 @@ import { fetchModelOptions, type ModelOption } from '@/init/models-dev'
 import { makeOAuthLoginRunner, type OAuthLoginResult } from '@/init/oauth-login'
 
 import { buildOAuthCallbacks } from './oauth-callbacks'
-import { c, done, errorLine } from './ui'
+import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
 
 // ESC and Ctrl+C both produce clack's cancel symbol (the keypress layer
 // aliases both to the same "cancel" action — there's no way to tell them
@@ -1005,50 +1005,7 @@ async function runSlackFlow(): Promise<StepResult<CollectedInputs['channelSecret
   let sub: SubStep = 'bot'
   let botToken: string | undefined
 
-  note(
-    [
-      '1. https://api.slack.com/apps → Create New App → From a manifest.',
-      '   Pick your workspace, then paste this JSON manifest:',
-      '',
-      '   {',
-      '     "display_information": { "name": "TypeClaw" },',
-      '     "features": {',
-      '       "bot_user": { "display_name": "TypeClaw", "always_online": true }',
-      '     },',
-      '     "oauth_config": {',
-      '       "scopes": {',
-      '         "bot": [',
-      '           "app_mentions:read", "chat:write", "users:read", "files:read",',
-      '           "channels:history", "channels:read",',
-      '           "groups:history",   "groups:read",',
-      '           "im:history",       "im:read",',
-      '           "mpim:history",     "mpim:read"',
-      '         ]',
-      '       }',
-      '     },',
-      '     "settings": {',
-      '       "event_subscriptions": {',
-      '         "bot_events": [',
-      '           "app_mention",',
-      '           "message.channels", "message.groups",',
-      '           "message.im",       "message.mpim"',
-      '         ]',
-      '       },',
-      '       "socket_mode_enabled": true',
-      '     }',
-      '   }',
-      '',
-      '2. Install to Workspace, then OAuth & Permissions →',
-      '   copy the Bot User OAuth Token (xoxb-...).',
-      '3. Basic Information → App-Level Tokens → Generate Token and',
-      '   Scopes, add the connections:write scope, and copy the',
-      '   token (xapp-...). Socket Mode needs this; the manifest',
-      '   cannot grant it.',
-      '4. Invite the bot to any private channel or DM you want it in:',
-      '   /invite @TypeClaw',
-    ].join('\n'),
-    'Get a Slack bot',
-  )
+  printSlackAppManifestSetup()
 
   while (true) {
     if (sub === 'bot') {

package/src/cli/model.ts

@@ -25,7 +25,7 @@ const ADD_PROVIDER_SENTINEL = '__add-provider__'
 const setSub = defineCommand({
   meta: {
     name: 'set',
-    description: 'set or update a model profile (default | fast | vision | <custom>)',
+    description: 'set or update a model profile (default | fast | deep | vision | <custom>)',
   },
   args: {
     profile: {
@@ -206,6 +206,7 @@ async function pickProfileName(): Promise<string> {
     options: [
       { value: 'default', label: 'default', hint: 'active model for new sessions' },
       { value: 'fast', label: 'fast', hint: 'optional alias used by some subagents' },
+      { value: 'deep', label: 'deep', hint: 'optional alias used by some subagents' },
       { value: 'vision', label: 'vision', hint: 'optional alias used by some subagents' },
     ],
     initialValue: 'default',

package/src/cli/ui.ts

@@ -124,3 +124,98 @@ export function errorLine(reason: string): string {
 export function successLine(message: string): string {
   return `${c.green('●')} ${message}`
 }
+
+// The exact JSON manifest a user pastes into
+// https://api.slack.com/apps → From a manifest. Kept as a typed object so
+// the file stays a single source of truth and `JSON.stringify` guarantees
+// the rendered text is always valid JSON — no risk of a stray comma or
+// quote slipping in through hand-formatting.
+export const SLACK_APP_MANIFEST = {
+  display_information: { name: 'TypeClaw' },
+  features: {
+    bot_user: { display_name: 'TypeClaw', always_online: true },
+    // Enable the Messages tab so users can DM the bot from its app profile,
+    // and disable the Home tab — TypeClaw does not publish a custom App Home
+    // view, and leaving it enabled would surface an empty default tab.
+    app_home: {
+      home_tab_enabled: false,
+      messages_tab_enabled: true,
+      messages_tab_read_only_enabled: false,
+    },
+  },
+  oauth_config: {
+    scopes: {
+      // Ordered alphabetically so the manifest stays a stable diff target.
+      // Read scopes cover every conversation type the agent might observe;
+      // write scopes (chat, files, im/mpim/groups, pins, reactions) let the
+      // agent post replies, upload attachments, open DMs, pin messages, and
+      // react to messages. `channels:join` lets the bot self-join public
+      // channels it's invited to discuss in.
+      bot: [
+        'app_mentions:read',
+        'channels:history',
+        'channels:join',
+        'channels:read',
+        'chat:write',
+        'emoji:read',
+        'files:read',
+        'files:write',
+        'groups:history',
+        'groups:read',
+        'groups:write',
+        'im:history',
+        'im:read',
+        'im:write',
+        'mpim:history',
+        'mpim:read',
+        'mpim:write',
+        'pins:read',
+        'pins:write',
+        'reactions:read',
+        'reactions:write',
+        'users:read',
+      ],
+    },
+  },
+  settings: {
+    event_subscriptions: {
+      bot_events: ['app_mention', 'message.channels', 'message.groups', 'message.im', 'message.mpim'],
+    },
+    socket_mode_enabled: true,
+  },
+} as const
+
+// Prints the "create a Slack app from a manifest" walkthrough so the JSON
+// payload is **flush-left and copy-pasteable**. Clack's `note()` wraps
+// content inside a box with `│` borders on both sides, and `log.message()`
+// still prefixes every line with a `│  ` guide column — neither survives a
+// click-and-drag copy. This helper splits the walkthrough into three
+// segments: a boxed prose intro, a raw-stdout JSON block, and a boxed
+// follow-up. The JSON block is emitted via `process.stdout.write` so it
+// carries zero terminal decoration.
+export function printSlackAppManifestSetup(output: NodeJS.WritableStream = process.stdout): void {
+  note(
+    [
+      '1. https://api.slack.com/apps → Create New App → From a manifest.',
+      '   Pick your workspace, then paste the JSON manifest printed below',
+      `   (it is rendered flush-left so you can ${c.bold('click-drag and copy')} cleanly).`,
+    ].join('\n'),
+    'Get a Slack bot',
+  )
+  output.write('\n')
+  output.write(`${JSON.stringify(SLACK_APP_MANIFEST, null, 2)}\n`)
+  output.write('\n')
+  note(
+    [
+      '2. Install to Workspace, then OAuth & Permissions →',
+      '   copy the Bot User OAuth Token (xoxb-...).',
+      '3. Basic Information → App-Level Tokens → Generate Token and',
+      '   Scopes, add the connections:write scope, and copy the',
+      '   token (xapp-...). Socket Mode needs this; the manifest',
+      '   cannot grant it.',
+      '4. Invite the bot to any private channel or DM you want it in:',
+      '   /invite @TypeClaw',
+    ].join('\n'),
+    'Finish Slack setup',
+  )
+}

package/src/init/dockerfile.ts

@@ -561,6 +561,8 @@ ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
 
+${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
+
 ${LAYER_5_CHROME_FOR_TESTING}
 
 ${cloudflaredLayer}${renderEntrypointShimLayer()}
@@ -638,6 +640,8 @@ ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
 
+${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
+
 ${LAYER_5_CHROME_FOR_TESTING}
 
 ${renderEntrypointShimLayer()}
@@ -699,6 +703,114 @@ const LAYER_4_AGENT_BROWSER_INSTALL = `# Layer 4 (volatile): install agent-brows
 RUN --mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\
     bun install -g agent-browser`
 
+// Layer 4.5: shim the agent-browser binary with a wrapper that calls
+// \`agent-browser close\` before \`open\`/\`goto\`/\`navigate\` when headed
+// mode is requested. Works around vercel-labs/agent-browser issue #1083
+// ("headed silently ignored on existing session"): when a daemon is
+// already running with a headless browser, subsequent commands with
+// --headed / AGENT_BROWSER_HEADED reuse the existing headless browser
+// regardless of the requested mode. Three upstream fix PRs (#660, #370,
+// #387) have been open and unmerged for months as of 2026-05, so we
+// patch this locally rather than block on upstream.
+//
+// Allowlist, not denylist. The wrapper only pre-closes on the three
+// commands that explicitly start a new browsing session (\`open\`,
+// \`goto\`, \`navigate\`). Every other agent-browser subcommand — \`click\`,
+// \`snapshot\`, \`chat\`, \`connect\`, \`batch\`, \`tab\`, \`record\`, \`trace\`,
+// \`stream\`, \`cookies\`, \`network\`, ... — passes through untouched.
+// Rationale: those subcommands may operate on the live browser/page
+// state (cookies, in-progress recording, attached external CDP, etc.),
+// and a pre-close from us would silently destroy it. The user-reported
+// scenario for #1083 (\"\`agent-browser open <url> --headed\` after a
+// previous headless invocation\") is fully covered because the
+// follow-up commands inherit the now-headed browser the \`open\`
+// pre-close forced. An earlier draft used a deny-list approach that
+// pre-closed on every non-skip subcommand under headed env; oracle
+// self-review flagged the state-destruction risk for stateful commands,
+// and the allowlist fix is the resulting narrower contract.
+//
+// Truthy contract mirrors upstream's \`env_var_is_truthy\`
+// (cli/src/flags.rs:183): any non-empty value EXCEPT case-insensitive
+// "0" / "false" / "no" counts as truthy. So
+// \`AGENT_BROWSER_HEADED=yes\`, \`=y\`, \`=on\`, \`=anything-non-falsy\` all
+// trigger the workaround — matching what upstream's CLI parser would
+// see — instead of the original narrower 1|true match that left the
+// bug present for legitimate truthy values.
+//
+// Re-entrancy is defended at two layers. (1) The pre-close path is
+// \`open\`/\`goto\`/\`navigate\` only, and the close subcommand isn't in the
+// allowlist, so the pre-close never recurses through the wrapper into
+// another pre-close. (2) \`_TYPECLAW_AGENT_BROWSER_HEADED_HANDLED=1\` is
+// set on the env passed to both the pre-close and the final exec; if a
+// future subcommand we don't recognize shells out to \`agent-browser\` as
+// a subprocess while headed env is still set, the child sees the guard
+// and bypasses straight to .real without recursing.
+const LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER = `# Layer 4.5 (cheap): wrap agent-browser to work around upstream issue
+# #1083 (--headed / AGENT_BROWSER_HEADED ignored on existing session).
+# See src/init/dockerfile.ts for the full rationale.
+RUN mv /usr/local/bin/agent-browser /usr/local/bin/agent-browser.real \\
+ && cat > /usr/local/bin/agent-browser <<'TYPECLAW_AGENT_BROWSER_WRAPPER_EOF' \\
+ && chmod +x /usr/local/bin/agent-browser
+#!/bin/sh
+# typeclaw wrapper for agent-browser — see src/init/dockerfile.ts.
+set -e
+real="\${TYPECLAW_AGENT_BROWSER_REAL:-/usr/local/bin/agent-browser.real}"
+# Re-entrancy guard: if the wrapper invoked us, skip straight to the real
+# binary. Prevents infinite recursion if a subcommand shells out to
+# agent-browser while AGENT_BROWSER_HEADED is still set.
+if [ "\${_TYPECLAW_AGENT_BROWSER_HEADED_HANDLED:-}" = "1" ]; then
+  exec "$real" "$@"
+fi
+# Pre-close is only needed when the caller is requesting headed mode.
+# Match upstream's env_var_is_truthy contract (cli/src/flags.rs:183):
+# truthy = any non-empty value except case-insensitive "0", "false", "no".
+# Argv triggers: bare --headed, --headed=true, --headed=1. (A bare
+# --headed followed by a separate "false" argument is upstream-supported
+# to FORCE headless; the wrapper still pre-closes on the --headed match
+# and the real binary launches headless — wasted close, correct end
+# state. The narrower argv match keeps the wrapper from triggering on
+# unrelated --headed-prefixed flags that may exist in future upstream
+# versions.)
+headed=0
+val=\${AGENT_BROWSER_HEADED:-}
+lower=$(printf '%s' "$val" | tr '[:upper:]' '[:lower:]')
+case "$lower" in
+  ''|'0'|'false'|'no') ;;
+  *) headed=1 ;;
+esac
+for arg in "$@"; do
+  case "$arg" in
+    --headed|--headed=true|--headed=1) headed=1; break ;;
+  esac
+done
+if [ "$headed" != "1" ]; then
+  exec "$real" "$@"
+fi
+# Allowlist of commands where pre-close is safe and necessary. Only
+# user-visible "start a new browsing session" verbs go here. Everything
+# else (click, snapshot, chat, connect, batch, tab, record, trace,
+# stream, cookies, ...) may depend on live browser/page state and must
+# not be pre-closed by us.
+first=""
+for arg in "$@"; do
+  case "$arg" in
+    -*) continue ;;
+    *) first="$arg"; break ;;
+  esac
+done
+case "$first" in
+  open|goto|navigate) ;;
+  *) exec "$real" "$@" ;;
+esac
+# Best-effort pre-close. If the daemon is already gone, the real binary
+# prints "No active sessions" and exits 0 — safe to call unconditionally.
+# We discard its output so it never pollutes the caller's stdout/stderr,
+# and we tolerate failures (network blip, stale socket) by falling
+# through to the real command anyway.
+_TYPECLAW_AGENT_BROWSER_HEADED_HANDLED=1 "$real" close >/dev/null 2>&1 || true
+exec env _TYPECLAW_AGENT_BROWSER_HEADED_HANDLED=1 "$real" "$@"
+TYPECLAW_AGENT_BROWSER_WRAPPER_EOF`
+
 // Layer 5: download the pinned Chrome for Testing build into
 // ~/.agent-browser/browsers/. NO cache mount on that path because the
 // runtime needs the binary in the image. System shared libraries are

package/src/init/index.ts

@@ -37,6 +37,14 @@ const CONFIG_FILE = 'typeclaw.json'
 const CRON_FILE = 'cron.json'
 const PACKAGE_FILE = 'package.json'
 
+// Seeded into `typeclaw.json#roles.member.match[]` whenever a chat adapter
+// (slack-bot, discord-bot, telegram-bot, kakaotalk) is wired. The "*" rule
+// matches every channel session on every platform, so the built-in `member`
+// role (which already carries `channel.respond`) covers any inbound the
+// router sees. Without this, freshly-hatched agents silently drop every
+// chat message — see scaffold() and ensureDefaultChatMemberMatch() below.
+const DEFAULT_CHAT_MEMBER_MATCH_RULE = '*'
+
 const MARKDOWN_FILES = ['AGENTS.md', 'IDENTITY.md', 'SOUL.md', 'USER.md'] as const
 
 // `packages/` is a bun workspace root (see `workspaces` in buildPackageJson).
@@ -543,6 +551,11 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
   if (options.withTelegram) channels['telegram-bot'] = {}
   if (options.withKakaotalk) channels.kakaotalk = {}
   if (Object.keys(channels).length > 0) config.channels = channels
+  // See DEFAULT_CHAT_MEMBER_MATCH_RULE for why this is here. GitHub is wired
+  // separately (writeGithubChannelForInit) and seeds per-repo member.match
+  // entries instead of the wildcard, so a github-only init stays scoped to
+  // the repos the operator opted in to.
+  if (Object.keys(channels).length > 0) config.roles = { member: { match: [DEFAULT_CHAT_MEMBER_MATCH_RULE] } }
   await writeFile(join(root, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
 
   const cron = {
@@ -965,6 +978,8 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   if (options.channel === 'github') {
     await appendGithubMatchRules(options.cwd, options.repos)
     await maybeInstallGithubWebhooks(options, emit)
+  } else {
+    await ensureDefaultChatMemberMatch(options.cwd)
   }
 
   // Commit the typeclaw.json change so the agent folder isn't silently
@@ -1209,6 +1224,24 @@ async function appendGithubMatchRules(cwd: string, repos: readonly string[]): Pr
   await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
 }
 
+// Chat-adapter counterpart of appendGithubMatchRules. See
+// DEFAULT_CHAT_MEMBER_MATCH_RULE for the rationale. Set-union semantics: re-
+// running `typeclaw channel add` for additional chat adapters is a no-op on
+// the match list, and any pre-existing rules the operator hand-authored
+// (e.g. owner-claim's per-author entry on `owner`) are left intact.
+async function ensureDefaultChatMemberMatch(cwd: string): Promise<void> {
+  const path = join(cwd, CONFIG_FILE)
+  const parsed = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>
+  const roles = isObjectRecord(parsed.roles) ? { ...parsed.roles } : {}
+  const member = isObjectRecord(roles.member) ? { ...roles.member } : {}
+  const existing = Array.isArray(member.match) ? member.match.filter((v): v is string => typeof v === 'string') : []
+  if (existing.includes(DEFAULT_CHAT_MEMBER_MATCH_RULE)) return
+  member.match = [...existing, DEFAULT_CHAT_MEMBER_MATCH_RULE]
+  roles.member = member
+  parsed.roles = roles
+  await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
+}
+
 // Writes per-adapter field values into `secrets.json#channels.<adapter>`.
 // Refuses to overwrite existing fields: if the user already has e.g.
 // `botToken` recorded (from a prior `channel add` whose follow-up steps