dsh-oauth-login 0.2.4

package/src/model-error-hint.ts

@@ -0,0 +1,98 @@
+/** Provider-specific failure compatibility and user-facing model error copy. */
+
+import { LlmError } from '@deepseek-ai/dsh-llm'
+import type { LlmFailure } from '@deepseek-ai/dsh-llm'
+
+/**
+ * Default Harness `retryPolicy` codes. Keep aligned with
+ * `resolveRetryPolicy(undefined)` in `@deepseek-ai/dsh-llm`.
+ */
+export const TRANSIENT_MODEL_CODES = Object.freeze([
+  'EMPTY_RESPONSE',
+  'RATE_LIMIT',
+  'SERVER',
+  'TIMEOUT',
+  'TRANSPORT',
+])
+
+export const QUOTA_HINT = 'This is account quota or credits, not a temporary busy signal. Automatic retry will not refill it. Check the plan, usage window, or balance.'
+export const RATE_LIMIT_HINT = 'This is a request-rate or peak-busy limit. A 429 is often this, not an empty balance. After automatic retries end, wait and send another message. If Continue fails or the composer stays stuck, start a new chat.'
+export const TRANSIENT_HINT = 'After this turn ends, send another message to try again. If Continue fails or the composer stays stuck, start a new chat.'
+
+const SENTINELS = [
+  'Automatic retry will not refill it',
+  'request-rate or peak-busy limit',
+  'After this turn ends, send another message',
+] as const
+
+/** Stable Chat copy for one official `LlmError` code. Does not invent 5h vs weekly vs billing. */
+export function hintForCode(code: string): string | undefined {
+  if (code === 'QUOTA') return QUOTA_HINT
+  if (code === 'RATE_LIMIT') return RATE_LIMIT_HINT
+  if ((TRANSIENT_MODEL_CODES as readonly string[]).includes(code)) return TRANSIENT_HINT
+  return undefined
+}
+
+function alreadyHinted(message: string): boolean {
+  return SENTINELS.some(marker => message.includes(marker))
+}
+
+/** Read only the top-level Zhipu error code, never incidental request or message text. */
+function isZhipuPlanQuota(message: string): boolean {
+  const match = /^\s*429\s*:\s*(\{[\s\S]*\})\s*$/.exec(message)
+  if (match === null) return false
+  let payload: unknown
+  try {
+    payload = JSON.parse(match[1]!)
+  } catch (_malformedProviderJson) {
+    return false
+  }
+  return typeof payload === 'object' && payload !== null && !Array.isArray(payload)
+    && 'code' in payload && (payload.code === '1310' || payload.code === 1310)
+}
+
+/** Repair only observed route-specific classification gaps; keep all other official codes. */
+function providerFailure(failure: LlmFailure, provider: string | undefined): LlmFailure {
+  // The upstream word-boundary matcher recognizes "socket" but misses
+  // "WebSocket". Keep policy/protocol/size failures out of this narrow repair.
+  if (provider === 'pi-openai-codex' && failure.code === 'PI_AI_ERROR'
+    && (/^WebSocket error$/i.test(failure.message.trim())
+      || /^WebSocket closed (?:1000|1001|1005|1006|1011|1012|1013)(?:\s|$)/i.test(failure.message.trim()))) {
+    return { ...failure, code: 'TRANSPORT' }
+  }
+  if (provider === 'pi-openai-codex' && failure.code === 'PI_AI_ERROR'
+    && /\b(?:servers?|engine)\s+(?:are|is)\s+(?:currently\s+)?overloaded\b/i.test(failure.message)) {
+    return { ...failure, code: 'SERVER' }
+  }
+  if (provider === 'pi-zai-coding-cn' && failure.code === 'RATE_LIMIT'
+    && isZhipuPlanQuota(failure.message)) {
+    return { ...failure, code: 'QUOTA' }
+  }
+  return failure
+}
+
+/** Normalize known provider gaps before the official retry executor receives this failure. */
+export function hintFailure(failure: LlmFailure, provider?: string): LlmFailure {
+  const normalized = providerFailure(failure, provider)
+  const hint = hintForCode(normalized.code)
+  if (hint === undefined || alreadyHinted(normalized.message)) return normalized
+  return {
+    ...normalized,
+    message: `${normalized.message} ${hint}`,
+  }
+}
+
+/** Apply the same provider correction and hint to thrown failures, preserving diagnostics. */
+export function withModelErrorHint(error: unknown, provider?: string): unknown {
+  if (!(error instanceof LlmError)) return error
+  const hinted = hintFailure(error.failure, provider)
+  if (hinted === error.failure) return error
+  return new LlmError(hinted.message, hinted.code, {
+    cause: error,
+    ...error.failure.status === undefined ? {} : { status: error.failure.status },
+    ...error.failure.providerRetryAfterMs === undefined
+      ? {}
+      : { providerRetryAfterMs: error.failure.providerRetryAfterMs },
+    ...error.failure.requestId === undefined ? {} : { requestId: error.failure.requestId },
+  })
+}

package/src/native-tools.ts

@@ -0,0 +1,442 @@
+/**
+ * OAuth routes that already have provider-hosted search / image tools.
+ * DSH's web_search function tool would hide those and bill a second key.
+ */
+
+import type { Context as PiContext, StreamOptions } from '@earendil-works/pi-ai'
+import type { ReplayEnvelope, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { piLoginProviderByRoute } from './catalog.ts'
+
+/** DSH model-facing tools that steal traffic from a subscribed provider. */
+export const DSH_WEB_TOOL_NAMES = ['web_search', 'web_fetch'] as const
+
+/** Matching tool-web prompt sections. */
+export const DSH_WEB_SECTION_NAMES = ['tool:web_search', 'tool:web_fetch'] as const
+
+const DSH_WEB_TOOL_NAME_SET = new Set<string>(DSH_WEB_TOOL_NAMES)
+const DSH_WEB_SECTION_NAME_SET = new Set<string>(DSH_WEB_SECTION_NAMES)
+
+/** Precise xAI server-side X Search operations published by the provider. */
+export const XAI_SERVER_X_SEARCH_NAMES = [
+  'x_user_search',
+  'x_keyword_search',
+  'x_semantic_search',
+  'x_thread_fetch',
+] as const
+
+const XAI_SERVER_X_SEARCH_NAME_SET = new Set<string>(XAI_SERVER_X_SEARCH_NAMES)
+
+/**
+ * Hosted / server-executed names that can leak as client function calls
+ * after this plugin removes DSH's implementations from the route.
+ */
+export const HOSTED_CLIENT_LEAK_NAMES = [
+  ...XAI_SERVER_X_SEARCH_NAMES,
+  'web_search',
+  'web_fetch',
+  'image_generation',
+  'imagine_text_to_image',
+  'imagine_image_to_image',
+  'imagine_image_edit',
+] as const
+
+const HOSTED_CLIENT_LEAK_NAME_SET = new Set<string>(HOSTED_CLIENT_LEAK_NAMES)
+
+export interface NativeToolPolicy {
+  /** Attach hosted tools and hide DSH web_search / web_fetch. Default true. */
+  enabled: boolean
+  /** Also attach hosted image generation where the provider documents it. Default true. */
+  image: boolean
+}
+
+export const DEFAULT_NATIVE_TOOL_POLICY: NativeToolPolicy = {
+  enabled: true,
+  image: true,
+}
+
+export interface NativeToolPlan {
+  readonly providerId: string
+  readonly api: string
+  readonly hosted: readonly Record<string, unknown>[]
+  readonly guidance: string
+}
+
+const SEARCH_GUIDANCE =
+  'This turn already includes this account\'s native hosted search. Do not call web_search or web_fetch — those DSH tools are not available on this route.'
+
+const SEARCH_AND_IMAGE_GUIDANCE =
+  'This turn already includes this account\'s native hosted search and image generation. Do not call web_search or web_fetch — those DSH tools are not available on this route.'
+
+function responsesSearch(): Record<string, unknown> {
+  return { type: 'web_search' }
+}
+
+function responsesXSearch(): Record<string, unknown> {
+  return { type: 'x_search' }
+}
+
+function responsesImage(): Record<string, unknown> {
+  return { type: 'image_generation' }
+}
+
+function anthropicSearch(): Record<string, unknown> {
+  return { type: 'web_search_20250305', name: 'web_search' }
+}
+
+export function nativePlan(
+  providerId: string,
+  api: string | undefined,
+  policy: NativeToolPolicy = DEFAULT_NATIVE_TOOL_POLICY,
+): NativeToolPlan | undefined {
+  if (!policy.enabled) return undefined
+  switch (`${providerId}:${api ?? ''}`) {
+    case 'xai:openai-responses':
+      return {
+        providerId,
+        api: 'openai-responses',
+        hosted: [
+          responsesSearch(),
+          responsesXSearch(),
+          ...policy.image ? [responsesImage()] : [],
+        ],
+        guidance: policy.image ? SEARCH_AND_IMAGE_GUIDANCE : SEARCH_GUIDANCE,
+      }
+    case 'openai-codex:openai-codex-responses':
+      return {
+        providerId,
+        api: 'openai-codex-responses',
+        hosted: [
+          responsesSearch(),
+          ...policy.image ? [responsesImage()] : [],
+        ],
+        guidance: policy.image ? SEARCH_AND_IMAGE_GUIDANCE : SEARCH_GUIDANCE,
+      }
+    case 'anthropic:anthropic-messages':
+      return {
+        providerId,
+        api: 'anthropic-messages',
+        hosted: [anthropicSearch()],
+        guidance: SEARCH_GUIDANCE,
+      }
+    default:
+      return undefined
+  }
+}
+
+export function nativePlanForRoute(
+  route: string | undefined,
+  api: string | undefined,
+  policy: NativeToolPolicy = DEFAULT_NATIVE_TOOL_POLICY,
+): NativeToolPlan | undefined {
+  if (route === undefined) return undefined
+  const spec = piLoginProviderByRoute(route)
+  return spec === undefined ? undefined : nativePlan(spec.id, api, policy)
+}
+
+export function isDshWebToolName(name: string): boolean {
+  return DSH_WEB_TOOL_NAME_SET.has(name)
+}
+
+export function isDshWebSectionName(name: string): boolean {
+  return DSH_WEB_SECTION_NAME_SET.has(name)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * xAI's Responses stream currently exposes server-executed X Search details
+ * as custom tool calls. The outer `xs_call-*` id distinguishes those traces
+ * from a same-named client function, which Harness must still execute.
+ */
+export function isXaiServerXSearchCall(block: unknown): boolean {
+  if (!isRecord(block) || block.type !== 'tool-call') return false
+  if (typeof block.name !== 'string' || !XAI_SERVER_X_SEARCH_NAME_SET.has(block.name)) return false
+  if (typeof block.id !== 'string') return false
+  const outerId = block.id.split('|', 1)[0] ?? ''
+  return /^xs_call[-_]/.test(outerId)
+}
+
+/**
+ * Server-executed hosted search / image traces that Harness must not try to run.
+ * X Search leaks use `xs_call-*`. DSH `web_search` / `web_fetch` were stripped
+ * from this route, so a leftover same-named call is also a leak.
+ */
+export function isHostedServerToolCall(block: unknown): boolean {
+  if (!isRecord(block) || block.type !== 'tool-call') return false
+  if (typeof block.name !== 'string' || !HOSTED_CLIENT_LEAK_NAME_SET.has(block.name)) return false
+  if (isXaiServerXSearchCall(block)) return true
+  if (block.name === 'web_search' || block.name === 'web_fetch') return true
+  return block.name === 'image_generation' || block.name.startsWith('imagine_')
+}
+
+/**
+ * xAI hosted search hops arrive as empty `reasoning` blocks whose signature
+ * id is `tco_<response>_call-…`. The UI renders each as a blank Think card.
+ */
+export function isHostedSearchReasoningReplay(block: unknown): boolean {
+  if (!isRecord(block) || block.type !== 'reasoning') return false
+  const signature = block.thinkingSignature
+  if (typeof signature !== 'string' || signature.length === 0) return false
+  try {
+    const parsed = JSON.parse(signature) as { id?: unknown }
+    return typeof parsed.id === 'string' && parsed.id.startsWith('tco_')
+  } catch {
+    return signature.includes('"id":"tco_') || signature.startsWith('tco_')
+  }
+}
+
+function filterPiReplayState(
+  replayState: ReplayEnvelope | undefined,
+  dropped: ReadonlySet<number>,
+  forceStop: boolean,
+): ReplayEnvelope | undefined {
+  if (replayState === undefined
+    || !isRecord(replayState.response)
+    || replayState.response.kind !== 'pi-ai'
+    || !Array.isArray(replayState.blocks)) {
+    return replayState
+  }
+  let seenText = false
+  return {
+    ...replayState,
+    blocks: replayState.blocks.filter((block, index) => {
+      if (dropped.has(index) || isHostedSearchReasoningReplay(block)) return false
+      if (isRecord(block) && block.type === 'text') {
+        seenText = true
+        return true
+      }
+      // Hosted search keeps emitting English planning after the visible
+      // answer has started; DSH would pin that Think under the reply.
+      if (seenText && isRecord(block) && block.type === 'reasoning') return false
+      return true
+    }),
+    response: {
+      ...replayState.response,
+      ...forceStop ? { stopReason: 'stop' } : {},
+    },
+  }
+}
+
+function isEmptyReasoningText(text: string): boolean {
+  return text.trim().length === 0
+}
+
+/**
+ * Remove hosted server-side search / image traces after pi-ai 0.82.1 has
+ * mistaken them for client function calls. Other blocks retain stream order,
+ * actual client tools survive, and pi-ai replay metadata stays index-aligned.
+ */
+export async function* filterHostedServerToolTraces(
+  source: AsyncIterable<StreamChunk>,
+): AsyncGenerator<StreamChunk> {
+  const dropped = new Set<number>()
+  const pending = new Set<number>()
+  const reasoning = new Map<number, { chunks: StreamChunk[]; text: string; afterText: boolean }>()
+  let buffered: StreamChunk[] = []
+  let keptToolCalls = 0
+  let textStarted = false
+
+  const flush = function* (): Generator<StreamChunk> {
+    for (const item of buffered) {
+      if ('index' in item && dropped.has(item.index)) continue
+      yield item
+    }
+    buffered = []
+  }
+
+  const closeReasoning = function* (index: number, end?: StreamChunk): Generator<StreamChunk> {
+    const held = reasoning.get(index)
+    if (held === undefined) {
+      if (end !== undefined) yield end
+      return
+    }
+    reasoning.delete(index)
+    const ended = end?.type === 'block-end' && end.block.type === 'reasoning' ? end.block.text : ''
+    const text = ended.length > 0 ? ended : held.text
+    if (held.afterText || isEmptyReasoningText(text)) return
+    yield* held.chunks
+    if (end !== undefined) yield end
+  }
+
+  for await (const chunk of source) {
+    if (chunk.type === 'block-start' && chunk.blockType === 'text' || chunk.type === 'text-delta') {
+      textStarted = true
+    }
+
+    if (chunk.type === 'block-start' && chunk.blockType === 'reasoning') {
+      reasoning.set(chunk.index, { chunks: [chunk], text: '', afterText: textStarted })
+      continue
+    }
+
+    if (chunk.type === 'reasoning-delta' && reasoning.has(chunk.index)) {
+      const held = reasoning.get(chunk.index)
+      if (held !== undefined) {
+        held.chunks.push(chunk)
+        held.text += chunk.text
+      }
+      continue
+    }
+
+    if (chunk.type === 'block-end' && chunk.block.type === 'reasoning') {
+      yield* closeReasoning(chunk.index, chunk)
+      continue
+    }
+
+    if (chunk.type === 'block-start' && chunk.blockType === 'tool-call') {
+      pending.add(chunk.index)
+      buffered.push(chunk)
+      continue
+    }
+
+    if (pending.size > 0) {
+      buffered.push(chunk)
+      if (chunk.type === 'block-end' && chunk.block.type === 'tool-call' && pending.has(chunk.index)) {
+        if (isHostedServerToolCall(chunk.block)) dropped.add(chunk.index)
+        else keptToolCalls += 1
+        pending.delete(chunk.index)
+        if (pending.size === 0) yield* flush()
+      }
+      continue
+    }
+
+    if (chunk.type === 'finish') {
+      for (const index of [...reasoning.keys()]) yield* closeReasoning(index)
+      const forceStop = chunk.reason.kind === 'tool-calls' && dropped.size > 0 && keptToolCalls === 0
+      const replayState = filterPiReplayState(chunk.replayState, dropped, forceStop)
+      // DSH session.append rejects explicit `undefined` (lossless JSON). An
+      // error finish has no replay envelope; do not mint `replayState: undefined`.
+      yield {
+        type: 'finish' as const,
+        reason: forceStop ? { kind: 'stop' as const } : chunk.reason,
+        ...replayState === undefined ? {} : { replayState },
+      }
+      continue
+    }
+
+    yield chunk
+  }
+
+  // Preserve malformed/incomplete upstream evidence instead of silently
+  // swallowing it; the base adapter will normally finish every block.
+  for (const index of [...reasoning.keys()]) yield* closeReasoning(index)
+  if (buffered.length > 0) yield* flush()
+}
+
+/** @deprecated Use {@link filterHostedServerToolTraces}. */
+export const filterXaiServerToolTraces = filterHostedServerToolTraces
+
+/** A function-calling tool DSH registered as web_search / web_fetch. */
+export function isDshWebFunctionTool(tool: unknown): boolean {
+  if (!isRecord(tool)) return false
+  const name = typeof tool.name === 'string' ? tool.name : undefined
+  if (name === undefined || !isDshWebToolName(name)) return false
+  const type = tool.type
+  return type === undefined || type === 'function'
+}
+
+export function hostedToolKey(tool: Record<string, unknown>): string {
+  const type = typeof tool.type === 'string' ? tool.type : 'function'
+  const name = typeof tool.name === 'string' ? tool.name : ''
+  return `${type}:${name}`
+}
+
+export function applyNativeToolsToPayload(
+  payload: unknown,
+  providerId: string,
+  api: string | undefined,
+  policy: NativeToolPolicy = DEFAULT_NATIVE_TOOL_POLICY,
+): unknown {
+  const plan = nativePlan(providerId, api, policy)
+  if (plan === undefined || !isRecord(payload) || !Array.isArray(payload.tools)) return payload
+  const current = payload.tools
+  const kept = current.filter(tool => !isDshWebFunctionTool(tool))
+  const seen = new Set(
+    kept.filter(isRecord).map(tool => hostedToolKey(tool)),
+  )
+  const hosted = plan.hosted.filter(tool => {
+    const key = hostedToolKey(tool)
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+  return { ...payload, tools: [...hosted, ...kept] }
+}
+
+export function wrapOnPayload(
+  existing: StreamOptions['onPayload'],
+  providerId: string,
+  api: string | undefined,
+  policy: NativeToolPolicy = DEFAULT_NATIVE_TOOL_POLICY,
+): StreamOptions['onPayload'] {
+  if (nativePlan(providerId, api, policy) === undefined) return existing
+  return async (payload, model) => {
+    // This hook is installed only for an agent request whose context declared
+    // tools. If DSH web tools were the whole list, Pi may omit `tools` after
+    // they are filtered; materialize the list so hosted tools still reach the
+    // provider. Utility/text-only requests never install this hook.
+    const requestPayload = isRecord(payload) && !('tools' in payload)
+      ? { ...payload, tools: [] }
+      : payload
+    const injected = applyNativeToolsToPayload(requestPayload, providerId, api, policy)
+    if (existing === undefined) return injected
+    return await existing(injected, model)
+  }
+}
+
+export function filterPiContext(
+  context: PiContext,
+  providerId: string,
+  api: string | undefined,
+  policy: NativeToolPolicy = DEFAULT_NATIVE_TOOL_POLICY,
+): PiContext {
+  if (nativePlan(providerId, api, policy) === undefined || context.tools === undefined) return context
+  return {
+    ...context,
+    tools: context.tools.filter(tool => !isDshWebToolName(tool.name)),
+  }
+}
+
+/**
+ * Prepare one provider request as a single unit.
+ *
+ * Native tools are a property of this request, not of the provider account.
+ * A context without tools is a text-only call (reviewers, summaries, titles,
+ * and similar utility traffic), so its payload hook must stay untouched even
+ * when the provider serializer later emits `tools: []`.
+ */
+export function prepareNativeToolRequest<TOptions extends StreamOptions>(
+  context: PiContext,
+  options: TOptions,
+  providerId: string,
+  api: string | undefined,
+  policy: NativeToolPolicy = DEFAULT_NATIVE_TOOL_POLICY,
+): { context: PiContext; options: TOptions & StreamOptions } {
+  if (context.tools === undefined || nativePlan(providerId, api, policy) === undefined) {
+    return { context, options }
+  }
+  const onPayload = wrapOnPayload(options?.onPayload, providerId, api, policy)
+  return {
+    context: filterPiContext(context, providerId, api, policy),
+    options: onPayload === options.onPayload
+      ? options
+      : Object.assign({}, options, { onPayload }),
+  }
+}
+
+export function maskDshWebAssembly<
+  T extends {
+    tools: readonly { name: string }[]
+    sections: readonly { name: string; text: string }[]
+  },
+>(assembly: T, plan: NativeToolPlan): T {
+  return {
+    ...assembly,
+    tools: assembly.tools.filter(tool => !isDshWebToolName(tool.name)),
+    sections: [
+      ...assembly.sections.filter(section => !isDshWebSectionName(section.name)),
+      { name: 'oauth:native-tools', text: plan.guidance },
+    ],
+  }
+}

package/src/oauth-refresh.ts

@@ -0,0 +1,49 @@
+/**
+ * When to spend a refresh_token. Chat already refreshes via Models.getAuth;
+ * this helper is for status / boot / the host timer so the store does not sit
+ * on a stale expires stamp.
+ */
+
+/** Refresh when the stored access stamp is inside this window (Pi already skews expires by 5 min). */
+export const OAUTH_REFRESH_SOON_MS = 15 * 60 * 1000
+
+/** Host timer. Access lives ~6h; this is just how often we look. */
+export const OAUTH_REFRESH_POLL_MS = 15 * 60 * 1000
+
+/** After a failed refresh, do not hit the token endpoint again until this elapses. */
+export const OAUTH_REFRESH_COOLDOWN_MS = 5 * 60 * 1000
+
+const lastAttempt = new Map<string, number>()
+
+export function grantNeedsRefresh(expires: number, now = Date.now()): boolean {
+  return now >= expires - OAUTH_REFRESH_SOON_MS
+}
+
+export function refreshAttemptKey(storeId: string, providerId: string): string {
+  return `${storeId}\0${providerId}`
+}
+
+export function refreshOnCooldown(key: string, now = Date.now()): boolean {
+  const previous = lastAttempt.get(key)
+  return previous !== undefined && now - previous < OAUTH_REFRESH_COOLDOWN_MS
+}
+
+export function markRefreshAttempt(key: string, now = Date.now()): void {
+  lastAttempt.set(key, now)
+}
+
+export function clearRefreshAttempts(): void {
+  lastAttempt.clear()
+}
+
+export async function refreshGrant(
+  getAuth: (providerId: string) => Promise<unknown>,
+  providerId: string,
+): Promise<'ok' | 'failed'> {
+  try {
+    await getAuth(providerId)
+    return 'ok'
+  } catch {
+    return 'failed'
+  }
+}