npm - typeclaw - Versions diffs - 0.10.0 → 0.11.0 - Mend

typeclaw 0.10.0 → 0.11.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 (53) hide show

package/package.json +1 -1
package/src/agent/index.ts +37 -4
package/src/agent/restart-handoff/index.ts +91 -0
package/src/agent/restart-handoff/paths.ts +11 -0
package/src/agent/session-origin.ts +30 -10
package/src/agent/subagent-completion-reminder.ts +4 -2
package/src/agent/system-prompt.ts +1 -1
package/src/agent/tools/restart.ts +42 -1
package/src/agent/tools/skip-response.ts +157 -0
package/src/bundled-plugins/memory/README.md +18 -2
package/src/bundled-plugins/memory/index.ts +108 -6
package/src/bundled-plugins/memory/memory-logger.ts +33 -24
package/src/bundled-plugins/security/policies/prompt-injection.ts +1 -1
package/src/channels/adapters/github/auth-app.ts +53 -9
package/src/channels/adapters/github/auth-pat.ts +4 -1
package/src/channels/adapters/github/auth.ts +10 -0
package/src/channels/adapters/github/event-permissions.ts +83 -0
package/src/channels/adapters/github/inbound.ts +126 -1
package/src/channels/adapters/github/index.ts +60 -66
package/src/channels/adapters/github/outbound.ts +65 -17
package/src/channels/adapters/github/permission-guidance.ts +169 -0
package/src/channels/adapters/github/team-membership.ts +56 -0
package/src/channels/router.ts +213 -32
package/src/channels/schema.ts +8 -7
package/src/channels/types.ts +1 -1
package/src/cli/channel.ts +135 -38
package/src/cli/init.ts +133 -86
package/src/cli/inspect-controller.ts +66 -0
package/src/cli/inspect.ts +24 -32
package/src/cli/run.ts +24 -5
package/src/cli/tui.ts +34 -10
package/src/cli/tunnel.ts +453 -14
package/src/config/config.ts +35 -7
package/src/config/providers.ts +64 -56
package/src/init/env-file.ts +66 -0
package/src/init/hatching.ts +32 -5
package/src/init/index.ts +131 -39
package/src/init/validate-api-key.ts +31 -0
package/src/inspect/index.ts +5 -1
package/src/inspect/loop.ts +12 -1
package/src/inspect/replay.ts +15 -1
package/src/run/codex-fetch-observer.ts +377 -0
package/src/run/index.ts +12 -2
package/src/server/index.ts +59 -1
package/src/shared/protocol.ts +1 -1
package/src/skills/typeclaw-channel-github/SKILL.md +45 -1
package/src/skills/typeclaw-tunnels/SKILL.md +33 -1
package/src/tui/index.ts +17 -5
package/src/tunnels/index.ts +1 -0
package/src/tunnels/manager.ts +18 -0
package/src/tunnels/providers/cloudflare-named.ts +224 -0
package/src/tunnels/types.ts +17 -1
package/typeclaw.schema.json +25 -7

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

@@ -0,0 +1,169 @@
+import type { PermissionGap } from './event-permissions'
+export type GithubAuthType = 'pat' | 'app'
+// What kind of outbound API the adapter was trying to call when it got a
+// 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'
+// 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
+// missing access on the list-hooks endpoint:
+//   - 404 Not Found: the token cannot see the repo at all (private repo
+//     gated behind missing repository access — GitHub returns 404 instead of
+//     403 to avoid leaking the existence of private repos).
+//   - 403 Forbidden: the token sees the repo but lacks webhook-management
+//     permission, OR is blocked by an org SSO/SAML authorization gate.
+// Returns null for any other error (network, malformed slug, create-hook
+// failures, etc.) so the guidance only fires on the actual symptom.
+export function parseListHooksPermissionStatus(error: string): number | null {
+  const match = error.match(/^list hooks failed: (404|403)\b/)
+  if (match === null) return null
+  return Number(match[1])
+}
+// The labels below intentionally mirror github.com's current UI verbatim so a
+// user can grep their settings page for the exact string. If GitHub renames
+// any of these in a future redesign, update both here and the
+// `permissionGuidance` tests in lifecycle.test.ts.
+//
+//   Fine-grained PAT:
+//     Settings → Developer settings → Personal access tokens → Fine-grained tokens
+//     "Resource owner", "Repository access", "Repository permissions" → "Webhooks" → "Read and write", "Metadata" → "Read-only"
+//   GitHub App:
+//     Settings → Developer settings → GitHub Apps → <app> → Permissions & events
+//     "Repository permissions" → "Webhooks" → "Read and write"
+//     Install/configure on the org: <app settings> → Install App / Configure → "Repository access"
+//   Classic PAT (legacy, still supported by GitHub but we don't surface it in
+//     channel-add prompts):
+//     Settings → Developer settings → Personal access tokens (classic)
+//     Scope: "admin:repo_hook" (or full "repo" for private repositories)
+export function buildPermissionGuidance(
+  authType: GithubAuthType,
+  failures: ReadonlyArray<{ repo: string; status: number }>,
+): string {
+  const repoList = failures.map((f) => `${f.repo} (${f.status})`).join(', ')
+  const lines: string[] = [
+    `[github] webhook setup needs more access for: ${repoList}.`,
+    '  - 404 from GitHub means the token cannot see the repo (GitHub hides private repos behind 404 instead of 403).',
+    '  - 403 means the token sees the repo but lacks webhook permission, or is blocked by org SAML/SSO.',
+    '',
+  ]
+  if (authType === 'pat') {
+    lines.push(
+      '  Fix (fine-grained personal access token):',
+      '    1. Open https://github.com/settings/personal-access-tokens and edit the token TypeClaw is using.',
+      '    2. Under "Resource owner", select the org that owns the failing repos (e.g. the org in the slug above).',
+      '    3. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
+      '    4. Under "Repository permissions", set "Webhooks" to "Read and write" and "Metadata" to "Read-only".',
+      '    5. Save. If the org enforces SAML SSO, click "Configure SSO" next to the token and authorize the org.',
+      '',
+      '  Or (classic personal access token): grant the "admin:repo_hook" scope (or "repo" for private repos),',
+      '  and on a SAML-protected org click "Authorize" next to the token.',
+    )
+  } else {
+    lines.push(
+      '  Fix (GitHub App):',
+      '    1. Open https://github.com/settings/apps and edit the app TypeClaw is using.',
+      '    2. Under "Permissions & events" → "Repository permissions", set "Webhooks" to "Read and write". Save.',
+      '    3. From the app page, click "Install App" (or "Configure" if already installed) and select the org that owns the failing repos.',
+      '    4. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
+      '    5. If the app permissions changed in step 2, install owners must accept the updated permissions from the install page before the new access takes effect.',
+    )
+  }
+  return lines.join('\n')
+}
+// Always GitHub App: PATs don't have per-installation permission grants
+// (their access is gated by token scopes, surfaced by the existing 404/403
+// flow in webhook-register).
+export function buildAppPermissionPreflightGuidance(gaps: ReadonlyArray<PermissionGap>): string {
+  const lines = [
+    `[github] GitHub App installation is missing permissions for ${gaps.length} configured event ${gaps.length === 1 ? 'family' : 'families'}:`,
+  ]
+  for (const gap of gaps) {
+    const eventList = gap.events.join(', ')
+    const grantedLabel = gap.granted === null ? 'none' : gap.granted
+    const needLabel = gap.needsWrite ? 'Read and write' : 'Read-only'
+    lines.push(`  - ${gap.uiLabel}: granted=${grantedLabel}, need=${needLabel} (covers: ${eventList})`)
+  }
+  lines.push(
+    '',
+    '  Fix:',
+    '    1. Open https://github.com/settings/apps and edit the app TypeClaw is using.',
+    '    2. Under "Permissions & events" → "Repository permissions", set each missing permission above to the listed level. Save.',
+    '    3. Open the install page (Install App / Configure for the org) and accept the updated permissions request — the new access only takes effect after the install owner accepts.',
+    '    4. If the org enforces SAML SSO, ensure the App is authorized for the org from the org settings → Third-party Apps page.',
+    '',
+    '  Webhooks already received will continue to deliver, but payload fields and reply attempts that require the missing permission will fail with 403 ("Resource not accessible by integration") until the install is reaccepted.',
+  )
+  return lines.join('\n')
+}
+// The label and (for App auth) the level appear verbatim on github.com so
+// users can grep their settings page for the exact strings. The PAT scope
+// names are GitHub's canonical token-scope identifiers, also verbatim.
+const OUTBOUND_PERMISSION_FOR_KIND: Record<
+  OutboundEndpointKind,
+  { label: string; level: 'Read and write'; patScope: string; patFineGrained: string }
+> = {
+  'issue-comment': {
+    label: 'Issues',
+    level: 'Read and write',
+    patScope: 'repo (or public_repo for public repos)',
+    patFineGrained: 'Issues',
+  },
+  'pr-review-reply': {
+    label: 'Pull requests',
+    level: 'Read and write',
+    patScope: 'repo',
+    patFineGrained: 'Pull requests',
+  },
+  'discussion-comment': {
+    label: 'Discussions',
+    level: 'Read and write',
+    patScope: 'repo',
+    patFineGrained: 'Discussions',
+  },
+}
+// Decorate an outbound-API failure with the precise github.com permission a
+// user needs to enable. Called only on the 403 + "Resource not accessible by
+// integration" combination — other 403s (org SSO, suspended install) need
+// different remediation and would be mis-described here.
+export function buildOutboundPermissionGuidance(options: {
+  authType: GithubAuthType
+  endpointKind: OutboundEndpointKind
+}): string {
+  const perm = OUTBOUND_PERMISSION_FOR_KIND[options.endpointKind]
+  if (options.authType === 'app') {
+    return [
+      '',
+      `  Fix (GitHub App): the App needs "${perm.label}" → "${perm.level}".`,
+      '    1. Open https://github.com/settings/apps and edit the app TypeClaw is using.',
+      `    2. Under "Permissions & events" → "Repository permissions", set "${perm.label}" to "${perm.level}". Save.`,
+      '    3. Open the install page (Install App / Configure for the org) and accept the updated permissions request — the new access only takes effect after the install owner accepts.',
+    ].join('\n')
+  }
+  return [
+    '',
+    `  Fix (fine-grained personal access token): grant "${perm.patFineGrained}" → "Read and write" on the failing repo.`,
+    '    1. Open https://github.com/settings/personal-access-tokens and edit the token TypeClaw is using.',
+    `    2. Under "Repository permissions", set "${perm.patFineGrained}" to "Read and write". Save.`,
+    `    3. If the org enforces SAML SSO, click "Configure SSO" next to the token and authorize the org.`,
+    '',
+    `  Or (classic personal access token): grant the "${perm.patScope}" scope; SAML-protected orgs additionally need "Authorize" next to the token.`,
+  ].join('\n')
+}
+// 403 with this exact body is GitHub's signal that the call would succeed
+// with the right permissions. Other 403 bodies (e.g. "OAuth token… needs to
+// be authorized for this organization", suspended installation) need
+// different remediation, so the decoration matcher is intentionally narrow.
+const INTEGRATION_PERMISSION_DENIAL = 'Resource not accessible by integration'
+export function isOutboundPermissionDenial(status: number, body: string): boolean {
+  return status === 403 && body.includes(INTEGRATION_PERMISSION_DENIAL)
+}

package/src/channels/adapters/github/team-membership.ts ADDED Viewed

@@ -0,0 +1,56 @@
+// Best-effort "is the bot a member of this team?" lookup, used to gate
+// `pull_request.review_requested` inbounds when GitHub assigns a *team*
+// rather than a user as the reviewer.
+//
+// Cached per (org, slug, login) for the adapter's lifetime: team membership
+// changes rarely, and a stale cache costs us one missed review (the next
+// request rebuilds it). Errors fall closed (return false): we'd rather drop
+// a real review request than wake the agent on a team the bot isn't in.
+const ACTIVE_MEMBERSHIP_STATE = 'active'
+export type TeamMembershipChecker = (input: { org: string; slug: string; login: string }) => Promise<boolean>
+export function createTeamMembershipChecker(options: {
+  token: () => Promise<string>
+  fetchImpl?: typeof fetch
+}): TeamMembershipChecker {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const cache = new Map<string, boolean>()
+  return async ({ org, slug, login }) => {
+    const key = `${org}/${slug}#${login}`
+    const cached = cache.get(key)
+    if (cached !== undefined) return cached
+    const result = await lookup(fetchImpl, await options.token(), org, slug, login)
+    cache.set(key, result)
+    return result
+  }
+}
+async function lookup(
+  fetchImpl: typeof fetch,
+  token: string,
+  org: string,
+  slug: string,
+  login: string,
+): Promise<boolean> {
+  const url = `https://api.github.com/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(slug)}/memberships/${encodeURIComponent(login)}`
+  let res: Response
+  try {
+    res = await fetchImpl(url, {
+      headers: {
+        accept: 'application/vnd.github+json',
+        authorization: `Bearer ${token}`,
+        'x-github-api-version': '2022-11-28',
+      },
+    })
+  } catch {
+    return false
+  }
+  if (res.status === 404) return false
+  if (!res.ok) return false
+  const body = (await res.json().catch(() => null)) as { state?: unknown } | null
+  return typeof body?.state === 'string' && body.state === ACTIVE_MEMBERSHIP_STATE
+}