npm - typeclaw - Versions diffs - 0.18.0 → 0.20.0 - Mend

typeclaw 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

package/package.json +1 -1
package/src/agent/index.ts +9 -1
package/src/agent/live-subagents.ts +4 -0
package/src/agent/model-overrides.ts +77 -0
package/src/agent/plugin-tools.ts +53 -4
package/src/agent/session-origin.ts +32 -10
package/src/agent/tools/channel-react.ts +79 -0
package/src/agent/tools/grant-role.ts +102 -8
package/src/agent/tools/spawn-subagent.ts +1 -0
package/src/agent/tools/subagent-access.ts +67 -0
package/src/agent/tools/subagent-cancel.ts +11 -6
package/src/agent/tools/subagent-output.ts +10 -2
package/src/bundled-plugins/github-cli-auth/gh-command.ts +372 -0
package/src/bundled-plugins/github-cli-auth/index.ts +42 -0
package/src/bundled-plugins/github-cli-auth/token-class.ts +11 -0
package/src/bundled-plugins/reviewer/skills/code-review.ts +18 -1
package/src/bundled-plugins/security/policies/secret-exfil-bash.ts +9 -2
package/src/channels/adapters/discord-bot.ts +242 -7
package/src/channels/adapters/github/inbound.ts +40 -55
package/src/channels/adapters/github/index.ts +89 -18
package/src/channels/adapters/github/membership.ts +4 -0
package/src/channels/adapters/github/permission-guidance.ts +20 -1
package/src/channels/adapters/github/reactions.ts +142 -0
package/src/channels/adapters/slack-bot-slash-commands.ts +3 -1
package/src/channels/adapters/slack-bot.ts +4 -4
package/src/channels/commands.ts +10 -0
package/src/channels/engagement.ts +30 -2
package/src/channels/github-token-bridge.ts +42 -0
package/src/channels/index.ts +6 -0
package/src/channels/manager.ts +6 -0
package/src/channels/membership.ts +9 -0
package/src/channels/router.ts +295 -42
package/src/channels/types.ts +42 -0
package/src/cli/inspect.ts +3 -0
package/src/cli/ui.ts +6 -0
package/src/commands/index.ts +54 -4
package/src/init/dockerfile.ts +60 -0
package/src/init/validate-api-key.ts +15 -1
package/src/inspect/loop.ts +12 -1
package/src/permissions/permissions.ts +24 -0
package/src/plugin/context.ts +8 -0
package/src/plugin/manager.ts +3 -0
package/src/plugin/types.ts +6 -0
package/src/run/bundled-plugins.ts +9 -0
package/src/run/index.ts +4 -0
package/src/skills/typeclaw-channel-github/SKILL.md +80 -43

package/src/channels/adapters/github/permission-guidance.ts CHANGED Viewed

@@ -6,7 +6,12 @@ export type GithubAuthType = 'pat' | 'app'
 // permission-failure response. Each value maps to a distinct GitHub App
 // permission family (and, for PATs, a distinct scope), so each surfaces a
 // different remediation message.
-export type OutboundEndpointKind = 'issue-comment' | 'pr-review-reply' | 'discussion-comment'
+export type OutboundEndpointKind =
+  | 'issue-comment'
+  | 'pr-review-reply'
+  | 'discussion-comment'
+  | 'issue-reaction'
+  | 'pr-review-comment-reaction'
 // Parses webhook-register errors of the shape `list hooks failed: <status> <body>`.
 // Returns the status code when it matches the two shapes GitHub emits for
@@ -127,6 +132,20 @@ const OUTBOUND_PERMISSION_FOR_KIND: Record<
     patScope: 'repo',
     patFineGrained: 'Discussions',
   },
+  // Reactions on an issue/PR body or an issue comment go through the Issues
+  // permission family; reactions on a PR review comment go through Pull requests.
+  'issue-reaction': {
+    label: 'Issues',
+    level: 'Read and write',
+    patScope: 'repo (or public_repo for public repos)',
+    patFineGrained: 'Issues',
+  },
+  'pr-review-comment-reaction': {
+    label: 'Pull requests',
+    level: 'Read and write',
+    patScope: 'repo',
+    patFineGrained: 'Pull requests',
+  },
 }
 // Decorate an outbound-API failure with the precise github.com permission a

package/src/channels/adapters/github/reactions.ts ADDED Viewed

@@ -0,0 +1,142 @@
+import type { ReactionCallback, ReactionErrorCode, ReactionRef, ReactionResult } from '@/channels/types'
+import type { GithubAuthContext } from './auth'
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+import {
+  buildOutboundPermissionGuidance,
+  type GithubAuthType,
+  isOutboundPermissionDenial,
+  type OutboundEndpointKind,
+} from './permission-guidance'
+// The reactable target, distinguished by the webhook event the inbound came
+// from. The router collapses every github inbound to the same `chat`/
+// `externalMessageId` pair, so this kind — known only at classification time —
+// is what selects the right Reactions endpoint. `issue` covers both issue and
+// PR bodies (GitHub models a PR body as an issue for reactions); `discussion`
+// is unsupported until the GraphQL `addReaction` path lands, so the classifier
+// does not stamp it today.
+export type GithubReactionTarget =
+  | { kind: 'issue'; owner: string; repo: string; issueNumber: number }
+  | { kind: 'issue-comment'; owner: string; repo: string; commentId: number }
+  | { kind: 'pr-review-comment'; owner: string; repo: string; commentId: number }
+export function encodeGithubReactionRef(target: GithubReactionTarget): ReactionRef {
+  return { adapter: 'github', value: JSON.stringify(target) }
+}
+export function decodeGithubReactionRef(ref: ReactionRef): GithubReactionTarget | null {
+  if (ref.adapter !== 'github') return null
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(ref.value)
+  } catch {
+    return null
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const t = parsed as Record<string, unknown>
+  const owner = typeof t.owner === 'string' ? t.owner : null
+  const repo = typeof t.repo === 'string' ? t.repo : null
+  if (owner === null || repo === null) return null
+  if (t.kind === 'issue' && typeof t.issueNumber === 'number') {
+    return { kind: 'issue', owner, repo, issueNumber: t.issueNumber }
+  }
+  if ((t.kind === 'issue-comment' || t.kind === 'pr-review-comment') && typeof t.commentId === 'number') {
+    return { kind: t.kind, owner, repo, commentId: t.commentId }
+  }
+  return null
+}
+// GitHub's Reactions API takes a fixed vocabulary of content strings. Map the
+// adapter-generic emoji name onto it; anything outside the set is reported as
+// `unsupported` so the model gets a clear signal rather than a silent 422.
+const REACTION_CONTENT: Record<string, string> = {
+  eyes: 'eyes',
+  '+1': '+1',
+  thumbsup: '+1',
+  '-1': '-1',
+  thumbsdown: '-1',
+  laugh: 'laugh',
+  hooray: 'hooray',
+  tada: 'hooray',
+  confused: 'confused',
+  heart: 'heart',
+  rocket: 'rocket',
+}
+export function createGithubReactionCallback(deps: {
+  token: (context?: GithubAuthContext) => Promise<string>
+  authType: GithubAuthType
+  fetchImpl?: typeof fetch
+}): ReactionCallback {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async (req): Promise<ReactionResult> => {
+    if (req.adapter !== 'github') return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    const content = REACTION_CONTENT[req.emoji.replace(/^:|:$/g, '')]
+    if (content === undefined) {
+      return { ok: false, error: `github does not support reaction "${req.emoji}"`, code: 'unsupported' }
+    }
+    const target = decodeGithubReactionRef(req.reactionRef)
+    if (target === null) return { ok: false, error: 'unparseable github reaction ref', code: 'unsupported' }
+    const endpoint = reactionEndpoint(target)
+    const endpointKind: OutboundEndpointKind =
+      target.kind === 'pr-review-comment' ? 'pr-review-comment-reaction' : 'issue-reaction'
+    return await postReaction(fetchImpl, await deps.token({ repoSlug: `${target.owner}/${target.repo}` }), endpoint, {
+      content,
+      authType: deps.authType,
+      endpointKind,
+    })
+  }
+}
+function reactionEndpoint(target: GithubReactionTarget): string {
+  const base = `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}`
+  switch (target.kind) {
+    case 'issue':
+      return `${base}/issues/${target.issueNumber}/reactions`
+    case 'issue-comment':
+      return `${base}/issues/comments/${target.commentId}/reactions`
+    case 'pr-review-comment':
+      return `${base}/pulls/comments/${target.commentId}/reactions`
+  }
+}
+async function postReaction(
+  fetchImpl: typeof fetch,
+  token: string,
+  url: string,
+  options: { content: string; authType: GithubAuthType; endpointKind: OutboundEndpointKind },
+): Promise<ReactionResult> {
+  let response: Response
+  try {
+    response = await fetchImpl(url, {
+      method: 'POST',
+      headers: githubJsonHeaders(token),
+      body: JSON.stringify({ content: options.content }),
+    })
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
+  }
+  // 201 = reaction created, 200 = the actor already left this same reaction.
+  // Both are success: an :eyes: that's already there is the desired end state,
+  // so a duplicate webhook delivery (or a retried engage) must not surface an error.
+  if (response.status === 200 || response.status === 201) return { ok: true }
+  const text = await response.text().catch(() => '')
+  const baseError = `GitHub API ${response.status}${text !== '' ? `: ${text}` : ''}`
+  if (isOutboundPermissionDenial(response.status, text)) {
+    return {
+      ok: false,
+      error: `${baseError}${buildOutboundPermissionGuidance({ authType: options.authType, endpointKind: options.endpointKind })}`,
+      code: 'permission-denied',
+    }
+  }
+  return { ok: false, error: baseError, code: classifyStatus(response.status) }
+}
+function classifyStatus(status: number): ReactionErrorCode {
+  if (status === 403) return 'permission-denied'
+  if (status === 404) return 'not-found'
+  if (status === 429) return 'rate-limited'
+  return 'transient'
+}

package/src/channels/adapters/slack-bot-slash-commands.ts CHANGED Viewed

@@ -135,7 +135,9 @@ export const SLACK_SLASH_REPLY_AMBIGUOUS =
 export function commandResultReply(result: ExecuteCommandResult): string {
   switch (result.kind) {
     case 'handled':
-      return SLACK_SLASH_REPLY_ABORTED
+      // Dynamic commands (e.g. /help) carry their own reply; static control
+      // commands (/stop) leave it undefined and fall back to the fixed string.
+      return result.reply ?? SLACK_SLASH_REPLY_ABORTED
     case 'no-live-session':
       return SLACK_SLASH_REPLY_NO_LIVE_SESSION
     case 'permission-denied':

package/src/channels/adapters/slack-bot.ts CHANGED Viewed

@@ -51,7 +51,7 @@ import { slackTsToMillis } from './slack-bot-time'
 // slash_commands events we route vs drop. The ui.test.ts manifest-drift
 // test asserts equality between this set and SLACK_APP_MANIFEST.features.
 // slash_commands so the two can never silently diverge.
-export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['stop'])
+export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['help', 'stop'])
 // Resolvers fall back to the raw id on failure, so a name equal to the id
 // means resolution failed; we render the bare id rather than `id(id)`. The
@@ -459,14 +459,14 @@ export function createSlackMembershipResolver(deps: {
     }
     let bots = 0
-    let humans = 0
+    const humanMemberIds: string[] = []
     for (const userId of members.value.members ?? []) {
       const cached = userBotCache.get(userId)
       const isBot = cached ?? (await resolveSlackUserIsBot(fetchFn, deps.token, userId, deps.logger, userBotCache))
       if (isBot) bots++
-      else humans++
+      else humanMemberIds.push(userId)
     }
-    return { humans, bots, fetchedAt: now(), truncated: false }
+    return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated: false, humanMemberIds }
   }
 }

package/src/channels/commands.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import type { CommandInfo } from '@/commands'
+// Generated from registry metadata so the listing can never drift from the
+// actual command set. The `/` prefix is canonical across every surface; Slack
+// threads accept the `!` alias for the same names.
+export function formatChannelCommandHelp(commands: readonly CommandInfo[]): string {
+  if (commands.length === 0) return 'No commands are available.'
+  const lines = commands.map((command) => `/${command.name} — ${command.description}`)
+  return ['Available commands:', ...lines].join('\n')
+}

package/src/channels/engagement.ts CHANGED Viewed

@@ -81,10 +81,22 @@ export type EngagementInput = {
 export function decideEngagement(input: EngagementInput): EngagementDecision {
   const { message, config, key, ledger, now, participants, selfAliases, botInThread } = input
+  // Peer bots are excluded from the count — a 1-human-N-bot room is still
+  // "solo" for the fallback at the bottom.
+  const effectiveHumans = countEffectiveHumans(participants, input.membership, now)
   if (config.trigger.includes('dm') && message.isDm) return 'engage'
   if (config.trigger.includes('mention') && message.isBotMention) return 'engage'
   if (config.trigger.includes('reply') && message.replyToBotMessageId !== null) return 'engage'
+  // Sticky credit force-engages in EVERY context (groups included) for the
+  // full window. This gate is deliberately content-blind: it answers "am I in
+  // an active conversation with this author?", not "does THIS message need a
+  // reply?" — a boolean over membership cannot tell "where did you send it?"
+  // (reply) from "lol ok" (chatter). Selectivity is the MODEL's job: engaged
+  // group turns get a `composeTurnPrompt` nudge (keyed off `isMultiHumanGroup`)
+  // to answer real follow-ups and `NO_REPLY` chatter. Gating sticky off in
+  // groups instead (the prior approach) dropped genuine follow-ups outright.
   if (config.stickiness !== 'off' && ledger.consume(key, message.authorId, now)) {
     return 'engage'
   }
@@ -169,13 +181,29 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   // peer's first message it's caught forever.
   if (textTargetsAnyPeerBot(message.text, participants)) return 'observe'
-  const persistedHumans = participants.filter((p) => p.isBot !== true).length
-  const effectiveHumans = resolveEffectiveHumans(persistedHumans, input.membership, now)
   if (effectiveHumans <= 1 && !message.authorIsBot) return 'engage'
   return 'observe'
 }
+export function countEffectiveHumans(
+  participants: readonly ChannelParticipant[],
+  membership: MembershipCount | null,
+  now: number,
+): number {
+  const persistedHumans = participants.filter((p) => p.isBot !== true).length
+  return resolveEffectiveHumans(persistedHumans, membership, now)
+}
+// A multi-human group is where the prompt's default "answer everything"
+// eagerness needs tempering. The router reads this in `route()` to decide
+// whether to append the group-chat nudge that tells the model to be selective
+// (answer real follow-ups, `NO_REPLY` chatter) on its engaged turns. DMs and
+// solo-human channels skip the nudge — there, replying to everything is right.
+export function isMultiHumanGroup(isDm: boolean, effectiveHumans: number): boolean {
+  return !isDm && effectiveHumans > 1
+}
 function textTargetsAnyPeerBot(text: string, participants: readonly ChannelParticipant[]): boolean {
   const haystack = text.toLocaleLowerCase()
   for (const p of participants) {

package/src/channels/github-token-bridge.ts ADDED Viewed

@@ -0,0 +1,42 @@
+// Decoupled from ChannelRouter on purpose: minting a token for an arbitrary
+// bash `gh` command is adjacent to channels but is not routing, and a global
+// singleton would leak resolver state across tests. One instance is created in
+// run/index.ts and threaded to both the plugin loader and the channel manager.
+export type GithubTokenResolveResult = { kind: 'token'; token: string } | { kind: 'unavailable'; reason: string }
+export type ResolveGithubTokenForRepo = (repoSlug: string) => Promise<GithubTokenResolveResult>
+export type GithubTokenBridge = {
+  resolveTokenForRepo: ResolveGithubTokenForRepo
+  registerResolver: (resolver: (repoSlug: string) => Promise<string>) => () => void
+}
+const NO_RESOLVER_REASON =
+  'GitHub App token unavailable; the GitHub channel adapter is not running or failed to start. ' +
+  'Check `typeclaw logs` and `secrets.json#channels.github`.'
+export function createGithubTokenBridge(): GithubTokenBridge {
+  let current: ((repoSlug: string) => Promise<string>) | null = null
+  return {
+    resolveTokenForRepo: async (repoSlug) => {
+      const resolver = current
+      if (resolver === null) return { kind: 'unavailable', reason: NO_RESOLVER_REASON }
+      try {
+        const token = await resolver(repoSlug)
+        return { kind: 'token', token }
+      } catch (err) {
+        return { kind: 'unavailable', reason: err instanceof Error ? err.message : String(err) }
+      }
+    },
+    registerResolver: (resolver) => {
+      current = resolver
+      return () => {
+        // Only clear if still the active resolver: a stop() racing a newer
+        // start() must not wipe the newer registration.
+        if (current === resolver) current = null
+      }
+    },
+  }
+}

package/src/channels/index.ts CHANGED Viewed

@@ -1,4 +1,10 @@
 export { createChannelManager, type ChannelManager, type ChannelManagerOptions } from './manager'
+export {
+  createGithubTokenBridge,
+  type GithubTokenBridge,
+  type GithubTokenResolveResult,
+  type ResolveGithubTokenForRepo,
+} from './github-token-bridge'
 export {
   createChannelRouter,
   type ChannelRouter,

package/src/channels/manager.ts CHANGED Viewed

@@ -12,6 +12,7 @@ import { createGithubAdapter, type GithubAdapter } from './adapters/github'
 import { createKakaotalkAdapter, type KakaotalkAdapter } from './adapters/kakaotalk'
 import { createSlackBotAdapter, type SlackBotAdapter } from './adapters/slack-bot'
 import { createTelegramBotAdapter, type TelegramBotAdapter } from './adapters/telegram-bot'
+import type { GithubTokenBridge } from './github-token-bridge'
 import { createChannelRouter, type ChannelRouter, type ClaimHandler, type CreateSessionForChannel } from './router'
 import {
   ADAPTER_IDS,
@@ -84,6 +85,10 @@ export type ChannelManagerOptions = {
   // Production wiring (`src/run/index.ts`) always passes the agent's
   // Stream; tests typically omit it.
   stream?: Stream
+  // Write-side of the GithubTokenBridge. The github adapter publishes its
+  // per-repo App token minter here on start (App auth only) so plugin hooks
+  // can resolve a token for ad-hoc `gh` commands. Tests omit it.
+  githubTokenBridge?: GithubTokenBridge
 }
 export type ChannelManager = {
@@ -199,6 +204,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
         logger,
         tunnelUrl: () => options.tunnelUrlForChannel?.('github') ?? null,
         tunnelConfiguredForChannel: () => options.tunnelConfiguredForChannel?.('github') ?? false,
+        ...(options.githubTokenBridge !== undefined ? { githubTokenBridge: options.githubTokenBridge } : {}),
       })
     }
     if (name === 'telegram-bot') {

package/src/channels/membership.ts CHANGED Viewed

@@ -21,6 +21,15 @@ export type MembershipCount = {
   bots: number
   fetchedAt: number
   truncated: boolean
+  // Identities of the human members, present ONLY when the adapter enumerated
+  // the COMPLETE current membership and classified every listed member in the
+  // same pass that produced `humans`. When set, `humanMemberIds.length` equals
+  // `humans` by construction, so a consumer can prove "every human in the room
+  // is X" by resolving each id — something the bare `humans` count cannot do.
+  // Left undefined by approximate/truncated/history-derived reads and by
+  // adapters that cannot enumerate members (Telegram, KakaoTalk); consumers
+  // that need a completeness proof must fail closed when it is absent.
+  humanMemberIds?: readonly string[]
 }
 export type MembershipResolverFailure = { kind: 'transient' } | { kind: 'permanent' }