typeclaw 0.45.0 → 0.46.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 (147) hide show
  1. package/README.md +1 -1
  2. package/package.json +3 -2
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +67 -25
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/loop-guard.ts +208 -10
  7. package/src/agent/multimodal/index.ts +1 -1
  8. package/src/agent/multimodal/look-at.ts +78 -44
  9. package/src/agent/multimodal/looker.ts +151 -39
  10. package/src/agent/network/response-body.ts +26 -0
  11. package/src/agent/network/safe-http.ts +198 -0
  12. package/src/agent/plugin-tools.ts +438 -162
  13. package/src/agent/provider-error.ts +62 -4
  14. package/src/agent/restart/index.ts +61 -40
  15. package/src/agent/restart-handoff/index.ts +73 -4
  16. package/src/agent/retry-same-ref.ts +66 -0
  17. package/src/agent/reviewer-bash-policy.ts +42 -1
  18. package/src/agent/session-origin.ts +2 -0
  19. package/src/agent/subagent-drain.ts +117 -7
  20. package/src/agent/subagents.ts +77 -18
  21. package/src/agent/throttle-circuit.ts +25 -5
  22. package/src/agent/tool-error-remediation.ts +72 -0
  23. package/src/agent/tool-file-safety.ts +1050 -0
  24. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  25. package/src/agent/tools/channel-reply.ts +15 -1
  26. package/src/agent/tools/channel-send.ts +17 -1
  27. package/src/agent/tools/ddg.ts +16 -2
  28. package/src/agent/tools/post-github-review.ts +199 -0
  29. package/src/agent/tools/spawn-subagent.ts +21 -18
  30. package/src/agent/tools/webfetch/fetch.ts +143 -183
  31. package/src/agent/tools/webfetch/tool.ts +2 -3
  32. package/src/agent/tools/websearch.ts +23 -2
  33. package/src/agent/tools-without-local-file-operands.ts +27 -0
  34. package/src/agent/turn-runner.ts +109 -15
  35. package/src/bundled-plugins/backup/index.ts +2 -1
  36. package/src/bundled-plugins/backup/runner.ts +2 -1
  37. package/src/bundled-plugins/doc-render/render.ts +93 -12
  38. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  39. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  40. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  41. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  42. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  43. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  44. package/src/bundled-plugins/memory/README.md +23 -11
  45. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  46. package/src/bundled-plugins/memory/citations.ts +22 -9
  47. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  48. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  49. package/src/bundled-plugins/memory/index.ts +0 -4
  50. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  51. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  52. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  53. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  54. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  55. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  56. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  57. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  58. package/src/bundled-plugins/reviewer/index.ts +2 -2
  59. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  60. package/src/bundled-plugins/reviewer/skills/code-review.ts +24 -9
  61. package/src/bundled-plugins/scout/scout.ts +8 -0
  62. package/src/bundled-plugins/security/index.ts +4 -4
  63. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  64. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  65. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  66. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  67. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  68. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  69. package/src/channels/adapters/discord-bot.ts +91 -10
  70. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  71. package/src/channels/adapters/discord-id.ts +4 -0
  72. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  73. package/src/channels/adapters/discord.ts +57 -7
  74. package/src/channels/adapters/github/auth-app.ts +41 -12
  75. package/src/channels/adapters/github/index.ts +23 -11
  76. package/src/channels/adapters/github/review-submitter.ts +302 -0
  77. package/src/channels/adapters/kakaotalk-channel-resolver.ts +12 -1
  78. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  79. package/src/channels/adapters/kakaotalk-typing.ts +127 -0
  80. package/src/channels/adapters/kakaotalk.ts +19 -0
  81. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  82. package/src/channels/adapters/slack-bot.ts +19 -8
  83. package/src/channels/adapters/slack-classify.ts +21 -2
  84. package/src/channels/adapters/slack.ts +59 -7
  85. package/src/channels/adapters/telegram-bot.ts +18 -5
  86. package/src/channels/adapters/webex-bot.ts +8 -3
  87. package/src/channels/adapters/webex.ts +8 -3
  88. package/src/channels/fetch-attachment.ts +43 -0
  89. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  90. package/src/channels/github-token-bridge.ts +10 -3
  91. package/src/channels/manager.ts +9 -0
  92. package/src/channels/router.ts +568 -12
  93. package/src/channels/types.ts +28 -1
  94. package/src/cli/channel.ts +1 -1
  95. package/src/cli/init.ts +1 -1
  96. package/src/cli/model.ts +57 -7
  97. package/src/compose/stop.ts +17 -5
  98. package/src/config/config.ts +6 -6
  99. package/src/config/models-mutation.ts +13 -1
  100. package/src/config/providers.ts +176 -0
  101. package/src/container/start.ts +49 -10
  102. package/src/doctor/checks.ts +3 -1
  103. package/src/doctor/commit.ts +2 -1
  104. package/src/doctor/file-ownership.ts +52 -0
  105. package/src/dreams/git.ts +2 -1
  106. package/src/git/hookless.ts +5 -0
  107. package/src/git/reconcile-ignored.ts +18 -5
  108. package/src/git/secret-history.ts +371 -0
  109. package/src/git/system-commit.ts +12 -6
  110. package/src/init/dockerfile.ts +86 -5
  111. package/src/init/index.ts +17 -5
  112. package/src/init/models-dev.ts +4 -0
  113. package/src/init/validate-api-key.ts +2 -0
  114. package/src/mcp/tools.ts +16 -3
  115. package/src/permissions/builtins.ts +3 -1
  116. package/src/plugin/context.ts +2 -0
  117. package/src/plugin/index.ts +1 -0
  118. package/src/plugin/manager.ts +4 -0
  119. package/src/plugin/types.ts +21 -0
  120. package/src/run/index.ts +40 -0
  121. package/src/run/llm-fetch-observer.ts +188 -13
  122. package/src/sandbox/build.ts +37 -15
  123. package/src/sandbox/canonical-secrets.ts +18 -0
  124. package/src/sandbox/env-exposure.ts +80 -0
  125. package/src/sandbox/errors.ts +13 -6
  126. package/src/sandbox/hidden-paths.ts +102 -44
  127. package/src/sandbox/index.ts +22 -4
  128. package/src/sandbox/package-install.ts +3 -27
  129. package/src/sandbox/policy.ts +11 -25
  130. package/src/sandbox/privileged-runtime.ts +255 -0
  131. package/src/sandbox/session-tmp.ts +8 -2
  132. package/src/sandbox/writable-zones.ts +204 -140
  133. package/src/secrets/index.ts +8 -0
  134. package/src/secrets/refresh-provider-oauth.ts +128 -0
  135. package/src/server/command-runner.ts +48 -4
  136. package/src/server/index.ts +4 -0
  137. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  138. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  139. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  140. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  141. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  142. package/src/skills/typeclaw-config/SKILL.md +5 -5
  143. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  144. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  145. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  146. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  147. package/typeclaw.schema.json +20 -0
@@ -60,7 +60,7 @@ export type InboundMessage = {
60
60
  // set this explicitly. `parentChat` carries the parent channel id when the
61
61
  // adapter knows it, so membership can be scoped to the room (channel), not
62
62
  // the thread. Absent ⇒ not a thread room (or the adapter cannot tell).
63
- room?: { kind: 'thread'; parentChat?: string }
63
+ room?: { kind: 'thread'; parentChat?: string; parentChatName?: string }
64
64
  text: string
65
65
  // Prompt-only context for replied-to / quoted / linked messages. Kept out
66
66
  // of `text` so the engagement gate sees only the human-authored body.
@@ -456,6 +456,7 @@ export type ListCallback = (args: ListChannelsArgs) => Promise<ListChannelsResul
456
456
  export type FetchAttachmentArgs = {
457
457
  ref: string
458
458
  filename?: string
459
+ maxBytes?: number
459
460
  }
460
461
 
461
462
  export type FetchAttachmentResult =
@@ -542,6 +543,32 @@ export type GithubReviewDecision = 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_RE
542
543
  // answer `unsupported`.
543
544
  export type ReviewStateResolver = (req: ReviewStateRequest) => Promise<ReviewStateResult>
544
545
 
546
+ export type ReviewFinding = {
547
+ path: string
548
+ line: number
549
+ side?: 'LEFT' | 'RIGHT'
550
+ startLine?: number
551
+ startSide?: 'LEFT' | 'RIGHT'
552
+ body: string
553
+ }
554
+
555
+ export type SubmitReviewRequest = {
556
+ adapter: AdapterId
557
+ workspace: string
558
+ chat: string
559
+ event: 'APPROVE' | 'REQUEST_CHANGES' | 'COMMENT'
560
+ body: string
561
+ comments: ReviewFinding[]
562
+ }
563
+
564
+ export type SubmitReviewResult =
565
+ | { ok: true; reviewId: number; state: string; downgraded?: boolean; reanchored?: ReviewFinding[] }
566
+ | { ok: false; error: string; code: SubmitReviewErrorCode; submitted?: boolean }
567
+
568
+ export type SubmitReviewErrorCode = 'unsupported' | 'permission-denied' | 'bad-anchor' | 'not-found' | 'transient'
569
+
570
+ export type ReviewSubmitter = (req: SubmitReviewRequest) => Promise<SubmitReviewResult>
571
+
545
572
  export function channelKeyId(key: { adapter: string; workspace: string; chat: string; thread: string | null }): string {
546
573
  return `${key.adapter}:${key.workspace}:${key.chat}:${key.thread ?? ''}`
547
574
  }
@@ -1518,7 +1518,7 @@ async function promptSlackAppToken(): Promise<string> {
1518
1518
  async function promptTelegramToken(): Promise<string> {
1519
1519
  note(
1520
1520
  [
1521
- 'Open Telegram and message @BotFather.',
1521
+ 'Open Telegram and message @BotFather or visit https://t.me/BotFather.',
1522
1522
  '/newbot → pick a name and username, copy the HTTP API token',
1523
1523
  ' (looks like 1234567890:ABCdef...).',
1524
1524
  'In @BotFather: /setprivacy → Disable, so the bot can see group messages.',
package/src/cli/init.ts CHANGED
@@ -1882,7 +1882,7 @@ function validatePositiveInteger(v: string, requiredMessage: string): string | u
1882
1882
  async function runTelegramFlow(): Promise<StepResult<CollectedInputs['channelSecrets']>> {
1883
1883
  note(
1884
1884
  [
1885
- 'Open Telegram and message @BotFather.',
1885
+ 'Open Telegram and message @BotFather or visit https://t.me/BotFather.',
1886
1886
  '/newbot → pick a name and username, copy the HTTP API token',
1887
1887
  ' (looks like 1234567890:ABCdef...).',
1888
1888
  'In @BotFather: /setprivacy → Disable, so the bot can see group messages.',
package/src/cli/model.ts CHANGED
@@ -15,6 +15,7 @@ import {
15
15
  } from '@/config/models-mutation'
16
16
  import {
17
17
  isKnownModelRef,
18
+ isModelRef,
18
19
  KNOWN_PROVIDERS,
19
20
  providerForModelRef,
20
21
  type KnownModelRef,
@@ -64,17 +65,19 @@ const setSub = defineCommand({
64
65
  },
65
66
  async run({ args }) {
66
67
  const cwd = ensureAgentDir()
67
- const profile = args.profile ?? (await pickProfileName())
68
- const picked = args.ref !== undefined ? await resolveExplicitRef(args.ref) : await pickModelRef(cwd)
68
+ // `model set <ref>` shorthand targets the `default` profile; a shorthand ref
69
+ // is resolved as an explicit ref (so its errors surface via resolvePickedRef's
70
+ // exit-1 path), and a bare/named-profile invocation falls back to the picker.
71
+ const shorthandRef = resolveShorthandRef(args.profile, args.ref)
72
+ const profile = shorthandRef !== undefined ? 'default' : (args.profile ?? (await pickProfileName()))
73
+ const picked = await resolvePickedRef(shorthandRef ?? args.ref, cwd)
69
74
 
70
75
  intro(`Setting model profile: ${profile} → ${picked.ref}`)
71
76
 
72
77
  // Gather every interactive/flag input BEFORE any write, so cancelling a
73
78
  // later prompt (e.g. the thinking-level select) aborts the whole command
74
- // without having already mutated typeclaw.json. Non-interactive (`--thinking`)
75
- // resolves the level from the flag; an interactive run (no flag, no explicit
76
- // ref) offers the prompt; explicit-ref scripted calls leave the level alone.
77
- const interactive = args.ref === undefined && args.thinking === undefined
79
+ // without having already mutated typeclaw.json.
80
+ const interactive = shouldPromptThinkingLevel(shorthandRef, args.ref, args.thinking)
78
81
  let thinking: { level: ThinkingLevel | undefined } | undefined
79
82
  if (args.thinking !== undefined) {
80
83
  const parsed = parseThinkingArg(args.thinking)
@@ -173,7 +176,7 @@ const addSub = defineCommand({
173
176
  },
174
177
  async run({ args }) {
175
178
  const cwd = ensureAgentDir()
176
- const picked = args.ref !== undefined ? await resolveExplicitRef(args.ref) : await pickModelRef(cwd)
179
+ const picked = await resolvePickedRef(args.ref, cwd)
177
180
 
178
181
  intro(`Adding model profile: ${args.profile} → ${picked.ref}`)
179
182
 
@@ -425,6 +428,30 @@ async function pickModelRef(cwd: string): Promise<PickedModelRef> {
425
428
  }
426
429
  }
427
430
 
431
+ // One-positional shorthand for `set`: `typeclaw model set <ref>` targets the
432
+ // `default` profile without repeating its name. It's shorthand ONLY when a
433
+ // single positional was given (no `<ref>` arg) and that positional parses as a
434
+ // model ref — so `model set fast` (a NAMED profile, not a ref) is NOT shorthand
435
+ // and still selects the `fast` profile interactively. Returns the ref when the
436
+ // invocation is shorthand, else undefined.
437
+ export function resolveShorthandRef(profile: string | undefined, ref: string | undefined): string | undefined {
438
+ return ref === undefined && profile !== undefined && isModelRef(profile) ? profile : undefined
439
+ }
440
+
441
+ // Whether `set` should OFFER the interactive thinking-level prompt. It should
442
+ // only when the ref itself was chosen interactively — i.e. no ref came from the
443
+ // command line (neither the explicit `<ref>` arg nor the shorthand) and no
444
+ // `--thinking` flag pinned the level. A named profile with no ref (e.g.
445
+ // `model set fast`) picks its ref interactively, so it MUST still prompt; keying
446
+ // this on `args.profile` instead of `shorthandRef` would wrongly suppress it.
447
+ export function shouldPromptThinkingLevel(
448
+ shorthandRef: string | undefined,
449
+ ref: string | undefined,
450
+ thinking: string | undefined,
451
+ ): boolean {
452
+ return shorthandRef === undefined && ref === undefined && thinking === undefined
453
+ }
454
+
428
455
  // Non-interactive `<ref>` path. Curated refs resolve from KNOWN_PROVIDERS, so
429
456
  // they need no metadata. Non-curated refs are looked up in the live catalog so
430
457
  // `customModels[ref]` carries the same metadata the interactive picker would
@@ -435,6 +462,14 @@ export async function resolveExplicitRef(
435
462
  loadCatalog: () => Promise<{ options: ModelOption[] }> = fetchModelOptions,
436
463
  ): Promise<PickedModelRef> {
437
464
  if (isKnownModelRef(ref)) return { ref }
465
+ // Intentionally NOT rejecting refs that miss our shipped registry — not even
466
+ // for a closed-set provider like openai-codex. The registry is a snapshot, not
467
+ // an authoritative catalog: OpenAI ships new Codex models (e.g. the gpt-5.6
468
+ // line) before we can update it, and a definite "this model doesn't exist" is
469
+ // only knowable from the backend's own 400, which the runtime path now
470
+ // classifies (see provider-error.ts). Blocking here would instead stop users
471
+ // from selecting a real, newly-shipped model. So an unknown closed-provider ref
472
+ // takes the same forward-compatible warning path as any other non-curated ref.
438
473
  const { options } = await loadCatalog()
439
474
  const option = options.find((candidate) => candidate.ref === ref)
440
475
  if (option === undefined) {
@@ -448,6 +483,21 @@ export async function resolveExplicitRef(
448
483
  return { ref, ...(meta !== undefined ? { meta } : {}) }
449
484
  }
450
485
 
486
+ // Resolve the model ref for `set`/`add`: an explicit `<ref>` arg is resolved
487
+ // (and enriched with catalog metadata) by `resolveExplicitRef`, while a bare
488
+ // invocation opens the interactive picker. Any resolution error surfaces via the
489
+ // standard CLI error line + non-zero exit instead of an unhandled-rejection
490
+ // stack trace. (Ref *shape*/support is validated downstream by set/addProfile.)
491
+ async function resolvePickedRef(ref: string | undefined, cwd: string): Promise<PickedModelRef> {
492
+ if (ref === undefined) return pickModelRef(cwd)
493
+ try {
494
+ return await resolveExplicitRef(ref)
495
+ } catch (e) {
496
+ console.error(errorLine(e instanceof Error ? e.message : String(e)))
497
+ process.exit(1)
498
+ }
499
+ }
500
+
451
501
  export type { PickedModelRef }
452
502
 
453
503
  async function listCredentialedModelOptions(refs: KnownModelRef[]): Promise<ModelOption[]> {
@@ -1,4 +1,4 @@
1
- import { resolveController, type StopResult } from '@/container'
1
+ import { type Controller, resolveController, type StopResult } from '@/container'
2
2
 
3
3
  import { discoverAgents, type AgentEntry } from './discover'
4
4
  import type { AgentResult } from './start'
@@ -14,17 +14,29 @@ export type ComposeStopOptions = {
14
14
  onProgress?: (event: ComposeStopEvent) => void
15
15
  }
16
16
 
17
+ // Injectable so tests drive orchestration without real Docker. Note the
18
+ // deliberate absence of the validateConfig guard that composeStart/Restart
19
+ // have: container identity derives from cwd, not a valid typeclaw.json, so a
20
+ // corrupted config must never block cleanup or a broken config strands a
21
+ // container that can only be removed by hand.
22
+ export type ComposeStopDeps = {
23
+ stop?: Controller['stop']
24
+ }
25
+
17
26
  export type ComposeStopResult = {
18
27
  agents: AgentEntry[]
19
28
  results: AgentResult<StopSuccess>[]
20
29
  }
21
30
 
22
- export async function composeStop({ rootCwd, onProgress }: ComposeStopOptions): Promise<ComposeStopResult> {
31
+ export async function composeStop(
32
+ { rootCwd, onProgress }: ComposeStopOptions,
33
+ { stop = (options) => resolveController().stop(options) }: ComposeStopDeps = {},
34
+ ): Promise<ComposeStopResult> {
23
35
  const agents = discoverAgents(rootCwd)
24
36
  const results = await Promise.all(
25
37
  agents.map(async (agent): Promise<AgentResult<StopSuccess>> => {
26
38
  onProgress?.({ kind: 'agent-start', name: agent.name })
27
- const result = await runOne(agent.name, agent.cwd)
39
+ const result = await runOne(agent.name, agent.cwd, stop)
28
40
  onProgress?.({ kind: 'agent-done', name: agent.name, result })
29
41
  return result
30
42
  }),
@@ -32,9 +44,9 @@ export async function composeStop({ rootCwd, onProgress }: ComposeStopOptions):
32
44
  return { agents, results }
33
45
  }
34
46
 
35
- async function runOne(name: string, cwd: string): Promise<AgentResult<StopSuccess>> {
47
+ async function runOne(name: string, cwd: string, stop: Controller['stop']): Promise<AgentResult<StopSuccess>> {
36
48
  try {
37
- const data = await resolveController().stop({ cwd })
49
+ const data = await stop({ cwd })
38
50
  if (!data.ok) return { name, ok: false, reason: data.reason }
39
51
  return { name, ok: true, data }
40
52
  } catch (error) {
@@ -415,12 +415,12 @@ export const relativeAgentPathSchema = z
415
415
  //
416
416
  // `from` is the symlink LOCATION and is fully configurable: an absolute container
417
417
  // path (e.g. `/root/.metabase-cli`) or a `~/`-prefixed path expanded against the
418
- // stage's HOME. Two stages create it: the entrypoint shim creates it at the real
419
- // container HOME (/root) for trusted/owner roles whose bash runs UNSANDBOXED, and
420
- // the per-tool bwrap sandbox emits a `--symlink` at the sandbox HOME (/tmp) for
421
- // low-trust roles — because `$HOME` differs between the two stages, a `~/` from
422
- // resolves to a different absolute path in each, which is exactly what each
423
- // consumer needs. The entrypoint refuses to clobber an existing non-symlink.
418
+ // stage's HOME. Two layers create it: the entrypoint shim creates it at the real
419
+ // container HOME (/root) for runtime-owned processes, and the per-tool bwrap
420
+ // sandbox emits a `--symlink` at the model-facing HOME (/tmp) for every role.
421
+ // Because `$HOME` differs between the two layers, a `~/` from resolves to the
422
+ // appropriate absolute path for each consumer. The entrypoint refuses to
423
+ // clobber an existing non-symlink.
424
424
  //
425
425
  // `from` SECURITY: it must not contain a null byte, must not be the root `/`, and
426
426
  // must not point INTO /agent (a self-referential loop). Kernel/virtual paths
@@ -307,7 +307,19 @@ function writeModels(
307
307
  try {
308
308
  writeFileSync(path, `${JSON.stringify(parsed, null, 2)}\n`)
309
309
  } catch (error) {
310
- return { ok: false, reason: `Failed to write ${CONFIG_FILE}: ${(error as Error).message}` }
310
+ const code = error instanceof Error && 'code' in error ? error.code : undefined
311
+ if (code === 'EACCES' || code === 'EPERM') {
312
+ return {
313
+ ok: false,
314
+ reason:
315
+ `${CONFIG_FILE} is not writable by the current user. ` +
316
+ `Inspect ownership with \`ls -ln "${path}"\`. If it is owned by another user and this agent folder belongs to you, repair it with \`sudo chown "$(id -u):$(id -g)" "${path}"\`.`,
317
+ }
318
+ }
319
+ return {
320
+ ok: false,
321
+ reason: `Failed to write ${CONFIG_FILE}: ${error instanceof Error ? error.message : String(error)}`,
322
+ }
311
323
  }
312
324
  // Final schema-pass for parity with every other host-side mutation that runs
313
325
  // through validateConfig. Mount checks etc. should never fail here because
@@ -400,6 +400,7 @@ export const KNOWN_PROVIDERS = {
400
400
  provider: 'zai',
401
401
  baseUrl: 'https://api.z.ai/api/paas/v4',
402
402
  reasoning: true,
403
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
403
404
  input: ['text'],
404
405
  cost: { input: 0.2, output: 1.1, cacheRead: 0, cacheWrite: 0 },
405
406
  contextWindow: 128000,
@@ -412,6 +413,7 @@ export const KNOWN_PROVIDERS = {
412
413
  provider: 'zai',
413
414
  baseUrl: 'https://api.z.ai/api/paas/v4',
414
415
  reasoning: true,
416
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
415
417
  input: ['text'],
416
418
  cost: { input: 0.6, output: 2.2, cacheRead: 0, cacheWrite: 0 },
417
419
  contextWindow: 200000,
@@ -424,6 +426,7 @@ export const KNOWN_PROVIDERS = {
424
426
  provider: 'zai',
425
427
  baseUrl: 'https://api.z.ai/api/paas/v4',
426
428
  reasoning: true,
429
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
427
430
  input: ['text'],
428
431
  cost: { input: 0.6, output: 2.2, cacheRead: 0, cacheWrite: 0 },
429
432
  contextWindow: 200000,
@@ -455,6 +458,7 @@ export const KNOWN_PROVIDERS = {
455
458
  provider: 'zai-coding',
456
459
  baseUrl: 'https://api.z.ai/api/coding/paas/v4',
457
460
  reasoning: true,
461
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
458
462
  input: ['text'],
459
463
  cost: { input: 0.2, output: 1.1, cacheRead: 0, cacheWrite: 0 },
460
464
  contextWindow: 128000,
@@ -467,6 +471,7 @@ export const KNOWN_PROVIDERS = {
467
471
  provider: 'zai-coding',
468
472
  baseUrl: 'https://api.z.ai/api/coding/paas/v4',
469
473
  reasoning: true,
474
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
470
475
  input: ['text'],
471
476
  cost: { input: 0.6, output: 2.2, cacheRead: 0, cacheWrite: 0 },
472
477
  contextWindow: 200000,
@@ -482,6 +487,7 @@ export const KNOWN_PROVIDERS = {
482
487
  provider: 'zai-coding',
483
488
  baseUrl: 'https://api.z.ai/api/coding/paas/v4',
484
489
  reasoning: true,
490
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
485
491
  input: ['text'],
486
492
  cost: { input: 1.0, output: 3.2, cacheRead: 0, cacheWrite: 0 },
487
493
  contextWindow: 200000,
@@ -494,6 +500,7 @@ export const KNOWN_PROVIDERS = {
494
500
  provider: 'zai-coding',
495
501
  baseUrl: 'https://api.z.ai/api/coding/paas/v4',
496
502
  reasoning: true,
503
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
497
504
  input: ['text'],
498
505
  cost: { input: 1.2, output: 4.0, cacheRead: 0, cacheWrite: 0 },
499
506
  contextWindow: 200000,
@@ -506,6 +513,7 @@ export const KNOWN_PROVIDERS = {
506
513
  provider: 'zai-coding',
507
514
  baseUrl: 'https://api.z.ai/api/coding/paas/v4',
508
515
  reasoning: true,
516
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
509
517
  input: ['text'],
510
518
  cost: { input: 1.4, output: 4.4, cacheRead: 0, cacheWrite: 0 },
511
519
  contextWindow: 200000,
@@ -653,6 +661,7 @@ export const KNOWN_PROVIDERS = {
653
661
  provider: 'minimax',
654
662
  baseUrl: 'https://api.minimax.io/v1',
655
663
  reasoning: true,
664
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
656
665
  input: ['text'],
657
666
  cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
658
667
  contextWindow: 204800,
@@ -665,6 +674,7 @@ export const KNOWN_PROVIDERS = {
665
674
  provider: 'minimax',
666
675
  baseUrl: 'https://api.minimax.io/v1',
667
676
  reasoning: true,
677
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
668
678
  input: ['text'],
669
679
  cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
670
680
  contextWindow: 204800,
@@ -677,6 +687,7 @@ export const KNOWN_PROVIDERS = {
677
687
  provider: 'minimax',
678
688
  baseUrl: 'https://api.minimax.io/v1',
679
689
  reasoning: true,
690
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
680
691
  input: ['text'],
681
692
  cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
682
693
  contextWindow: 204800,
@@ -689,6 +700,7 @@ export const KNOWN_PROVIDERS = {
689
700
  provider: 'minimax',
690
701
  baseUrl: 'https://api.minimax.io/v1',
691
702
  reasoning: true,
703
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
692
704
  input: ['text'],
693
705
  cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
694
706
  contextWindow: 204800,
@@ -734,6 +746,7 @@ export const KNOWN_PROVIDERS = {
734
746
  provider: 'deepseek',
735
747
  baseUrl: 'https://api.deepseek.com',
736
748
  reasoning: true,
749
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
737
750
  input: ['text'],
738
751
  cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
739
752
  contextWindow: 1000000,
@@ -746,6 +759,7 @@ export const KNOWN_PROVIDERS = {
746
759
  provider: 'deepseek',
747
760
  baseUrl: 'https://api.deepseek.com',
748
761
  reasoning: true,
762
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
749
763
  input: ['text'],
750
764
  cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
751
765
  contextWindow: 1000000,
@@ -753,6 +767,163 @@ export const KNOWN_PROVIDERS = {
753
767
  },
754
768
  },
755
769
  },
770
+ // Upstage (Solar) — console.upstage.ai pay-as-you-go API. OpenAI-compatible
771
+ // (Bearer auth + /chat/completions shape), so models go through pi-ai's
772
+ // `openai-completions` adapter with a custom baseUrl — same trick as
773
+ // Fireworks, Z.AI, MiniMax, DeepSeek, and Moonshot. api-key only; Upstage
774
+ // ships no OAuth flow. Keys are prefixed `up_`.
775
+ //
776
+ // baseUrl is `https://api.upstage.ai/v1` (the OpenAI-style `/v1` convention,
777
+ // like OpenAI/xAI/Moonshot — NOT the bare Anthropic/DeepSeek form). The SDK
778
+ // appends `/chat/completions`; `validate-api-key.ts` probes `${baseUrl}/models`.
779
+ // Some older third-party integrations (LangChain community, VoltAgent) point
780
+ // at the legacy `https://api.upstage.ai/v1/solar` path — that is deprecated;
781
+ // the console, the OpenAI-SDK example, and the agent docs all use bare `/v1`.
782
+ //
783
+ // Model lineup spans two families on the same Console API + key:
784
+ // * Closed chat models from the official agent API reference
785
+ // (console.upstage.ai/api/docs/for-agents) as of 2026-03-23:
786
+ // solar-pro3 (102B MoE / 12B active, 128K, flagship), solar-pro2
787
+ // (31B, 65K), solar-mini (10.7B, 32K, cheap/fast).
788
+ // * The open-weight Solar Open family: solar-open2 (Solar Open 2), a 102B
789
+ // MoE / 12B active model with a 128K context. It launched on the Console
790
+ // API for the Solar Agent Partner program (Stage 1, from 2026-07-17) —
791
+ // newer than the public docs snapshot above, so it is not yet in the
792
+ // public model-alias table; the model id is per Upstage's partner
793
+ // onboarding notice (docs: console.upstage.ai/api/chat).
794
+ // Every model here supports OpenAI-style function calling (required for agent
795
+ // use) and is text-only (Upstage's chat API exposes no image input). The
796
+ // `syn-pro` synthetic-data model is intentionally omitted: it does NOT
797
+ // support function calling and is useless as an agent model. Aliases (not the
798
+ // dated `-260323` suffixes) are used so they auto-forward to the latest
799
+ // versioned release.
800
+ //
801
+ // Costs are USD per 1M tokens from upstage.ai/pricing/api (VAT-exclusive).
802
+ // solar-pro3/pro2 publish an "Input(Cached)" cache-read rate ($0.015); no
803
+ // cache-write surcharge is published, so cacheWrite is 0. solar-mini
804
+ // publishes a single flat $0.15 rate with no cache line, so cacheRead and
805
+ // cacheWrite are both 0 (no published discount). solar-open2 has no published
806
+ // price yet (partner-program access, rate-limited rather than billed), so all
807
+ // four cost fields are 0 until Upstage publishes a Solar Open rate card.
808
+ //
809
+ // `compat` pins pi-ai's openai-completions adapter to Upstage's DOCUMENTED
810
+ // request surface. pi-ai only auto-detects compat for a known set of baseUrls
811
+ // (Cerebras, xAI, DeepSeek, …); api.upstage.ai is not among them, so without
812
+ // this it would default to OpenAI-native fields Upstage does not document and
813
+ // could reject. Per the Upstage Console API reference
814
+ // (console.upstage.ai/api/docs/for-agents): messages use system/user/assistant
815
+ // roles only (no `developer` role), output length is `max_tokens` (not
816
+ // `max_completion_tokens`), and `store` is not a documented field — so
817
+ // supportsDeveloperRole/supportsStore are false and maxTokensField is
818
+ // `max_tokens`. `stream_options.include_usage` and the `strict` field on tool
819
+ // definitions are both undocumented, so supportsUsageInStreaming and
820
+ // supportsStrictMode are false (both conservative — pi-ai defaults them to
821
+ // true, and Upstage only documents `strict` inside response_format.json_schema,
822
+ // never on tool defs). `reasoning_effort` IS documented for solar-pro3/pro2
823
+ // (and the solar-open2 chat template), so supportsReasoningEffort stays true
824
+ // there; solar-mini ignores it, so it is false and reasoning is off.
825
+ //
826
+ // Upstage documents reasoning_effort values minimal/low/medium/high only. pi
827
+ // adds an `xhigh` level that typeclaw's attention escalation can select
828
+ // (src/agent/attention-escalation.ts), and pi-ai passes the pi level straight
829
+ // through as reasoning_effort when no map is set — which would send the
830
+ // unsupported `xhigh`. `thinkingLevelMap` clamps xhigh -> high (and maps off ->
831
+ // null so nothing is sent) on the reasoning models so every emitted
832
+ // reasoning_effort is a value Upstage accepts. solar-mini needs no map (it
833
+ // never sends reasoning_effort).
834
+ upstage: {
835
+ id: 'upstage',
836
+ name: 'Upstage (Solar)',
837
+ baseUrl: 'https://api.upstage.ai/v1',
838
+ auth: ['api-key'],
839
+ apiKeyEnv: 'UPSTAGE_API_KEY',
840
+ oauthProviderId: null,
841
+ models: {
842
+ 'solar-open2': {
843
+ id: 'solar-open2',
844
+ name: 'Solar Open 2',
845
+ api: 'openai-completions',
846
+ provider: 'upstage',
847
+ baseUrl: 'https://api.upstage.ai/v1',
848
+ reasoning: true,
849
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
850
+ input: ['text'],
851
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
852
+ contextWindow: 128000,
853
+ maxTokens: 32000,
854
+ compat: {
855
+ supportsStore: false,
856
+ supportsDeveloperRole: false,
857
+ supportsReasoningEffort: true,
858
+ supportsUsageInStreaming: false,
859
+ supportsStrictMode: false,
860
+ maxTokensField: 'max_tokens',
861
+ },
862
+ },
863
+ 'solar-pro3': {
864
+ id: 'solar-pro3',
865
+ name: 'Solar Pro 3',
866
+ api: 'openai-completions',
867
+ provider: 'upstage',
868
+ baseUrl: 'https://api.upstage.ai/v1',
869
+ reasoning: true,
870
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
871
+ input: ['text'],
872
+ cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
873
+ contextWindow: 128000,
874
+ maxTokens: 32000,
875
+ compat: {
876
+ supportsStore: false,
877
+ supportsDeveloperRole: false,
878
+ supportsReasoningEffort: true,
879
+ supportsUsageInStreaming: false,
880
+ supportsStrictMode: false,
881
+ maxTokensField: 'max_tokens',
882
+ },
883
+ },
884
+ 'solar-pro2': {
885
+ id: 'solar-pro2',
886
+ name: 'Solar Pro 2',
887
+ api: 'openai-completions',
888
+ provider: 'upstage',
889
+ baseUrl: 'https://api.upstage.ai/v1',
890
+ reasoning: true,
891
+ thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
892
+ input: ['text'],
893
+ cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
894
+ contextWindow: 65000,
895
+ maxTokens: 16000,
896
+ compat: {
897
+ supportsStore: false,
898
+ supportsDeveloperRole: false,
899
+ supportsReasoningEffort: true,
900
+ supportsUsageInStreaming: false,
901
+ supportsStrictMode: false,
902
+ maxTokensField: 'max_tokens',
903
+ },
904
+ },
905
+ 'solar-mini': {
906
+ id: 'solar-mini',
907
+ name: 'Solar Mini',
908
+ api: 'openai-completions',
909
+ provider: 'upstage',
910
+ baseUrl: 'https://api.upstage.ai/v1',
911
+ reasoning: false,
912
+ input: ['text'],
913
+ cost: { input: 0.15, output: 0.15, cacheRead: 0, cacheWrite: 0 },
914
+ contextWindow: 32000,
915
+ maxTokens: 8000,
916
+ compat: {
917
+ supportsStore: false,
918
+ supportsDeveloperRole: false,
919
+ supportsReasoningEffort: false,
920
+ supportsUsageInStreaming: false,
921
+ supportsStrictMode: false,
922
+ maxTokensField: 'max_tokens',
923
+ },
924
+ },
925
+ },
926
+ },
756
927
  // Moonshot AI (Kimi) — Open Platform pay-as-you-go API. The platform exposes
757
928
  // an OpenAI-compatible surface at api.moonshot.ai/v1 (Bearer auth +
758
929
  // /chat/completions shape), so models go through pi-ai's `openai-completions`
@@ -938,6 +1109,11 @@ export const KNOWN_PROVIDER_VENDORS = {
938
1109
  name: 'DeepSeek',
939
1110
  providers: ['deepseek'],
940
1111
  },
1112
+ upstage: {
1113
+ id: 'upstage',
1114
+ name: 'Upstage (Solar)',
1115
+ providers: ['upstage'],
1116
+ },
941
1117
  moonshot: {
942
1118
  id: 'moonshot',
943
1119
  name: 'Moonshot (Kimi)',