savant-code 0.0.16 → 0.0.19

package/common/src/types/publisher.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod/v4'
+
+// Publisher ID validation schema - same restrictions as agent ID
+export const PublisherIdSchema = z
+  .string()
+  .regex(
+    /^[a-z0-9-]+$/,
+    'Publisher ID must contain only lowercase letters, numbers, and hyphens',
+  )
+
+// Publisher creation/update schema
+export const PublisherSchema = z.object({
+  id: PublisherIdSchema,
+  name: z.string().min(1, 'Publisher name is required'),
+  email: z.string().email().optional(),
+  bio: z.string().optional(),
+  avatar_url: z.string().url().optional(),
+})
+
+export type PublisherInput = z.infer<typeof PublisherSchema>
+
+export interface Publisher {
+  id: string
+  user_id: string | null
+  org_id: string | null
+  created_by: string
+  name: string
+  email: string | null
+  verified: boolean
+  bio: string | null
+  avatar_url: string | null
+  created_at: Date
+  updated_at: Date
+}
+
+export interface CreatePublisherRequest {
+  id: string
+  name: string
+  email?: string
+  bio?: string
+  avatar_url?: string
+  org_id?: string // Optional: if creating for an organization
+}
+
+export interface UpdatePublisherRequest {
+  name?: string
+  email?: string
+  bio?: string
+  avatar_url?: string
+}
+
+export interface PublisherProfileResponse {
+  id: string
+  user_id: string | null
+  org_id: string | null
+  created_by: string
+  name: string
+  email: string | null
+  verified: boolean
+  bio: string | null
+  avatar_url: string | null
+  created_at: Date
+  updated_at: Date
+  agentCount?: number
+  ownershipType: 'user' | 'organization'
+  organizationName?: string // If owned by org
+}

package/common/src/types/savant-free-session.ts

@@ -0,0 +1,295 @@
+import type { SavantFreeAccessTier } from '../constants/savant-free-models'
+
+/**
+ * Wire-level shapes returned by `/api/v1/savant-free/session`. Source of truth
+ * for the CLI (which deserializes these) and the server (which serializes
+ * them) — keep both in sync by importing this module from either side.
+ *
+ * The CLI uses these shapes directly; there are no client-only states.
+ */
+
+/**
+ * Usage counter surfaced to the CLI so the UI can render
+ * "N of M sessions used" alongside active state. Present when the
+ * joined model consumes SavantFree sessions. `recentCount` is the
+ * rounded session units since the last midnight Pacific reset at the time
+ * the response was produced — see also the standalone `rate_limited` status
+ * for the reject path.
+ */
+export interface SavantFreeRateLimit {
+  model: string
+  limit: number
+  /** 'pacific_day' for the daily premium/limited pools; 'pacific_week' for the
+   *  GLM 5.2 referral pool, which resets weekly. */
+  period: 'pacific_day' | 'pacific_week'
+  resetTimeZone: string
+  resetAt: string
+  /** Deprecated wire field kept for older clients. Session usage now resets
+   *  at midnight Pacific time rather than using a rolling window. */
+  windowHours: number
+  recentCount: number
+}
+
+export type SavantFreeRateLimitsByModel = Record<string, SavantFreeRateLimit>
+
+/**
+ * Referral status surfaced to the CLI model-selector so it can render an
+ * "invite friends" banner. The reward depends on the session's access tier:
+ *
+ *   - full tier    → unlock weekly GLM 5.2 sessions (`weeklySessionsRemaining`
+ *     and `resetAt` carry the live balance / next reset).
+ *   - limited tier → earn a daily free-session bonus (+1/day per qualified
+ *     referral, capped); the GLM-only fields are omitted, and `qualifiedCount`
+ *     carries the bonus sessions/day already earned (capped).
+ *
+ * Present on the pre-join (`none`) response. The CLI branches on the session's
+ * `accessTier` to pick the right copy; both variants share the share code,
+ * inviter name, and GitHub-linked flag.
+ */
+export interface SavantFreeReferralInfo {
+  /** The user's referral code (`user.referral_code`), used to build the share
+   *  link. */
+  code: string
+  /** The inviter's display name (`user.name`), used to personalize the invite
+   *  landing page ("X invited you to try SavantFree!"). Null when the user has no
+   *  name set. */
+  referrerName: string | null
+  /** Capped qualified-referral count for the tier's reward: full tier = weekly
+   *  GLM session entitlement; limited tier = daily-session bonus earned. The
+   *  CLI knows the relevant cap constant locally. */
+  qualifiedCount: number
+  /** GLM sessions still available this week (entitlement − used, ≥ 0). Full
+   *  tier only; omitted for the limited-tier daily-bonus variant. */
+  weeklySessionsRemaining?: number
+  /** ISO timestamp of the next weekly reset. Full tier only; omitted for the
+   *  limited-tier daily-bonus variant. */
+  resetAt?: string
+  /** Whether the current user has a GitHub account linked. Referrals only
+   *  qualify with a connected, sufficiently-old GitHub, so the CLI prompts
+   *  Google-only users to connect one. */
+  githubLinked: boolean
+}
+
+/** Pull the referral block off whichever session status carries it. Loose
+ *  parameter type for the same reason as `getRateLimitsByModel`. */
+export const getReferralInfo = (
+  session: { status: string } | null | undefined,
+): SavantFreeReferralInfo | undefined =>
+  session && 'referral' in session
+    ? (session as { referral?: SavantFreeReferralInfo }).referral
+    : undefined
+
+/** Pull the per-model shared session-quota snapshot off whichever statuses
+ *  carry it (active, ended, none). Returns undefined for terminal /
+ *  pre-join states that have no quota field. The parameter is intentionally
+ *  loose so the CLI can pass its `SavantFreeModel` (which adds the
+ *  client-only `takeover_prompt` variant) without a discriminated-union
+ *  ceremony at every call site. */
+export const getRateLimitsByModel = (
+  session: { status: string } | null | undefined,
+): SavantFreeRateLimitsByModel | undefined =>
+  session && 'rateLimitsByModel' in session
+    ? (session as { rateLimitsByModel?: SavantFreeRateLimitsByModel })
+        .rateLimitsByModel
+    : undefined
+
+export type SavantFreeBlockReason =
+  | 'country_not_allowed'
+  | 'anonymized_or_unknown_country'
+  | 'anonymous_network'
+  | 'missing_client_ip'
+  | 'unresolved_client_ip'
+  | 'ip_privacy_lookup_failed'
+
+export type SavantFreeIpPrivacySignal =
+  | 'anonymous'
+  | 'vpn'
+  | 'proxy'
+  | 'tor'
+  | 'relay'
+  | 'res_proxy'
+  | 'hosting'
+  | 'service'
+
+export type SavantFreeIpCheckResult =
+  'not_checked' | 'clean' | 'suspicious' | 'failed'
+
+export type SavantFreeAccessVerdict =
+  | 'allowed_clean'
+  | 'ipinfo_suspicious_spur_clean'
+  | 'corroborated_block'
+  | 'cloudflare_tor_block'
+  | 'spur_failed_limited'
+  | 'scamalytics_failed_limited'
+  | 'scamalytics_suspicious_limited'
+  | 'ipinfo_failed_limited'
+  | 'limited_other'
+
+export type SavantFreeIpCheckSource =
+  | 'not_checked'
+  | 'cloudflare_tor'
+  | 'ipinfo_clean'
+  | 'ipinfo_failed'
+  | 'ipinfo_only'
+  | 'spur_failed'
+  | 'scamalytics_failed'
+  | 'scamalytics_only'
+  | 'corroborated_soft'
+  | 'corroborated_hard'
+
+export interface SavantFreeGeoInfo {
+  /** Present for limited access so the model picker can explain why the
+   *  reduced model set is shown without re-running geo/IP logic locally. */
+  countryCode?: string | null
+  countryBlockReason?: SavantFreeBlockReason | null
+  ipPrivacySignals?: SavantFreeIpPrivacySignal[] | null
+}
+
+export type SavantFreeSessionState =
+  | ({
+      /** User has no session row. CLI must POST to start a session. Also
+       *  returned when `getSessionState` notices the user has been swept past
+       *  the grace window. */
+      status: 'none'
+      accessTier?: SavantFreeAccessTier
+      message?: string
+      /** Current quota snapshots for free models, keyed by model id. Lets
+       *  the picker show today's session usage before the user commits
+       *  to a model. */
+      rateLimitsByModel?: SavantFreeRateLimitsByModel
+      /** Referral status for the "invite friends" banner. Full tier advertises
+       *  GLM 5.2; limited tier advertises a daily free-session bonus. */
+      referral?: SavantFreeReferralInfo
+    } & SavantFreeGeoInfo)
+  | ({
+      status: 'active'
+      accessTier: SavantFreeAccessTier
+      instanceId: string
+      /** Model the active session is bound to — cannot change mid-session. */
+      model: string
+      admittedAt: string
+      expiresAt: string
+      remainingMs: number
+      /** Shared free-session quota for this model. */
+      rateLimit?: SavantFreeRateLimit
+      rateLimitsByModel?: SavantFreeRateLimitsByModel
+      /** Included for Web/Cloud picker reads that request full quota details. */
+      referral?: SavantFreeReferralInfo
+    } & SavantFreeGeoInfo)
+  | ({
+      /** Session is over. While `instanceId` is present we're inside the
+       *  server-side grace window — chat requests still go through so the
+       *  agent can finish, but the CLI must not accept new prompts. Once
+       *  `instanceId` is absent the session is fully gone and the user must
+       *  rejoin via POST.
+       *
+       *  Server-supplied form (in-grace) carries the timing fields; the
+       *  client may also synthesize a no-grace `{ status: 'ended' }` when a
+       *  poll reveals the row was swept. Both render the same UI. */
+      status: 'ended'
+      accessTier?: SavantFreeAccessTier
+      instanceId?: string
+      admittedAt?: string
+      expiresAt?: string
+      gracePeriodEndsAt?: string
+      gracePeriodRemainingMs?: number
+      /** Snapshot of the user's free-session quota at the moment the
+       *  session ended. Lets the post-session banner show "N of M sessions
+       *  used today" without an extra round-trip. */
+      rateLimitsByModel?: SavantFreeRateLimitsByModel
+      /** Included for Web/Cloud picker reads that request full quota details. */
+      referral?: SavantFreeReferralInfo
+    } & SavantFreeGeoInfo)
+  | {
+      /** Another CLI on the same account rotated our instance id. Polling
+       *  stops and the UI shows a "close the other CLI" screen. The server
+       *  returns this from GET /session when the caller's instance id
+       *  doesn't match the stored one; the chat-completions gate also
+       *  surfaces it as a 409 for fast in-flight feedback. */
+      status: 'superseded'
+    }
+  | {
+      /** Request originated outside the free-mode allowlist, or from an
+       *  unknown/anonymized location that cannot be trusted for free mode.
+       *  Returned before a session is started so users aren't rejected on
+       *  their first chat request. Terminal —
+       *  CLI stops polling and shows a "not available in your country"
+       *  screen. `countryCode` is the resolved country, or UNKNOWN. */
+      status: 'country_blocked'
+      message?: string
+      countryCode: string
+      countryBlockReason?: SavantFreeBlockReason
+      ipPrivacySignals?: SavantFreeIpPrivacySignal[]
+    }
+  | {
+      /** User has an active session bound to a different model. Returned
+       *  from POST /session when they pick a new model without ending their
+       *  current session first. The CLI shows a confirmation prompt: "End
+       *  your active DeepSeek session to switch?" → on confirm, DELETE then
+       *  re-POST with the new model. */
+      status: 'model_locked'
+      accessTier?: SavantFreeAccessTier
+      currentModel: string
+      requestedModel: string
+    }
+  | {
+      /** Requested model is valid but not selectable right now. */
+      status: 'model_unavailable'
+      accessTier?: SavantFreeAccessTier
+      requestedModel: string
+      availableHours: string
+    }
+  | {
+      /** Account is banned. Returned from every endpoint so banned bots can't
+       *  start a session at all. Terminal — CLI stops polling and shows a
+       *  banned message. */
+      status: 'banned'
+    }
+  | {
+      /** User has used up their shared free-session quota for the current
+       *  Pacific day. Returned from POST /session before a session is started.
+       *  `retryAfterMs` is the time until the next midnight Pacific
+       *  reset. Terminal for the CLI's current poll session; the user can exit
+       *  and come back later. */
+      status: 'rate_limited'
+      /** Desktop multi-session only: set to 'concurrent_sessions' when the
+       *  reject is the per-user concurrent-tab backstop rather than a
+       *  daily/weekly session pool — clients should say "close a tab", not
+       *  "daily limit". Absent on quota rejects. */
+      reason?: 'concurrent_sessions'
+      accessTier?: SavantFreeAccessTier
+      /** The savant-free model the user tried to join. */
+      model: string
+      /** Max session units permitted per period (e.g. 5/day premium, or the
+       *  user's weekly GLM referral entitlement). */
+      limit: number
+      period: 'pacific_day' | 'pacific_week'
+      resetTimeZone: string
+      resetAt: string
+      /** Deprecated wire field kept for older clients. */
+      windowHours: number
+      /** Session units since today's Pacific reset — will be ≥ limit. */
+      recentCount: number
+      /** Milliseconds from now until the next Pacific midnight reset. */
+      retryAfterMs: number
+    }
+  | {
+      /** SavantFree Desktop multi-session only: the user already holds an active
+       *  premium-bucket session and tried to admit a second one. Only one
+       *  premium-bucket model (DeepSeek V4 Pro / MiMo 2.5 Pro / Kimi / MiniMax
+       *  M3 / GLM 5.2) may run at a time per user; on the full tier unlimited
+       *  models (DeepSeek V4 Flash, MiMo 2.5) have no such cap. On the LIMITED
+       *  tier every model occupies the slot — one savant-free tab at a time. The
+       *  desktop client surfaces this and steers the tab to an unlimited model
+       *  (or closes the holding tab). Never returned to CLI/web, which run one
+       *  session per user. */
+      status: 'premium_slot_taken'
+      accessTier?: SavantFreeAccessTier
+      /** Model this tab tried to start. */
+      requestedModel: string
+      /** Model of the premium-bucket session already running. */
+      currentModel: string
+      /** Instance id of the existing premium-bucket session, so the client can
+       *  offer "switch to / close that one". */
+      currentInstanceId: string
+    }

package/common/src/types/savant-free-streak.ts

@@ -0,0 +1,6 @@
+export interface SavantFreeStreakResponse {
+  streak: number
+  todayUsed: boolean
+  lastUsageDate: string | null
+  timeZone: string
+}

package/common/src/types/session-state.ts

@@ -0,0 +1,237 @@
+import { z } from 'zod/v4'
+
+import { jsonValueSchema } from './json'
+import { MAX_AGENT_STEPS_DEFAULT } from '../constants/agents'
+
+import type { JSONValue } from './json'
+import type { Message } from './messages/savant-code-message'
+import type { ProjectFileContext } from '../util/file'
+
+export const toolCallSchema = z.object({
+  toolName: z.string(),
+  toolCallId: z.string(),
+  input: z.record(z.string(), jsonValueSchema),
+})
+export type ToolCall = z.infer<typeof toolCallSchema>
+
+export const subgoalSchema = z.object({
+  objective: z.string().optional(),
+  status: z
+    .enum(['NOT_STARTED', 'IN_PROGRESS', 'COMPLETE', 'ABORTED'])
+    .optional(),
+  plan: z.string().optional(),
+  logs: z.string().array(),
+})
+export type Subgoal = z.infer<typeof subgoalSchema>
+
+export type FsmPhase =
+  'idle' | 'red' | 'green' | 'audit' | 'self_correct' | 'complete'
+
+const FSM_PHASE_LIST: readonly FsmPhase[] = [
+  'idle',
+  'red',
+  'green',
+  'audit',
+  'self_correct',
+  'complete',
+] as const
+
+/**
+ * Type guard: narrows an unknown input to a valid FsmPhase.
+ * Used by SDK event handlers to defensively validate values that arrive over
+ * the SDK boundary. Foreign or malformed payloads revert to 'idle' rather
+ * than corrupting the FSM state.
+ *
+ * Source: FID-2026-0718-010 §3.2 Q11.
+ */
+export function isValidFsmPhase(value: unknown): value is FsmPhase {
+  return (
+    typeof value === 'string' &&
+    (FSM_PHASE_LIST as readonly string[]).includes(value)
+  )
+}
+
+/**
+ * Runtime activity indicator — distinct from FsmPhase.
+ * Tracks what Savant is doing RIGHT NOW (tool dispatch, model reasoning,
+ * sub-agent delegation, research) regardless of which Perfection Loop
+ * phase the FID is in. Auto-idles after a heartbeat timeout.
+ *
+ * Source: FID-2026-0718-009.
+ */
+export type AgentActivity =
+  | { kind: 'idle'; since: number }
+  | { kind: 'thinking'; model?: string; startedAt: number }
+  | { kind: 'tool'; toolName: string; startedAt: number; target?: string }
+  | {
+      kind: 'subagent'
+      agentType: string
+      startedAt: number
+      prompt?: string
+    }
+  | {
+      kind: 'researching'
+      query: string
+      startedAt: number
+      source: 'web' | 'docs'
+    }
+
+export type AgentState = {
+  /**
+   * @deprecated agentId is replaced by runId
+   */
+  agentId: string
+  agentType: AgentTemplateType | null
+  agentContext: Record<string, Subgoal>
+  ancestorRunIds: string[]
+  runId?: string
+  subagents: AgentState[]
+  childRunIds: string[]
+  messageHistory: Message[]
+  stepsRemaining: number
+  creditsUsed: number
+  directCreditsUsed: number
+  output?: Record<string, JSONValue>
+  parentId?: string
+  systemPrompt: string
+  toolDefinitions: Record<
+    string,
+    { description: string | undefined; inputSchema: JSONValue }
+  >
+  /**
+   * The accurate token count from the Anthropic API.
+   * This is updated on every agent step via the /api/v1/token-count endpoint.
+   */
+  contextTokenCount: number
+  /**
+   * ECHO Perfection Loop FSM phase. Starts at 'idle'. Transitions via transition_phase tool.
+   * Tool gating: write_file/str_replace blocked unless phase is 'green'.
+   */
+  fsmPhase?: FsmPhase
+  /**
+   * ECHO Perfection Loop iteration counter. Incremented on self_correct→green.
+   * Hard stop at 10 iterations to prevent runaway loops.
+   * Reset on audit→complete.
+   */
+  iterationCount?: number
+  /**
+   * Runtime activity indicator (FID-2026-0718-009). Distinct from fsmPhase.
+   * Tracks what the agent is doing right now regardless of FID lifecycle.
+   * Set by tool-executor, run-agent-step, spawn-agents handler, etc.
+   * Auto-idles after ACTIVE_IDLE_TIMEOUT_MS via the activityIdleTimer.
+   */
+  activity?: AgentActivity
+  /**
+   * @internal — setTimeout handle for the auto-idle transition. Not serialized
+   * to the SDK; cleared on cloneSessionState.
+   */
+  activityIdleTimer?: ReturnType<typeof setTimeout>
+
+  /**
+   * FID-2026-0725-085: Resolved context window for this model.
+   * Set by the CLI via CTX-007 wiring. Used by handleSteps to determine
+   * when to trigger context-pruner spawning (auto-compact Layer 3).
+   * Falls back to hardcoded defaults if not set.
+   */
+  maxContextLength?: number
+
+  /**
+   * FID-2026-0725-083: Goal condition for /goal command.
+   * When set, the agent evaluates whether the codebase state satisfies
+   * this condition after each task_completed call. If satisfied, the
+   * loop ends. If not, the agent continues iterating.
+   * Set by parsing <goal condition="..."> from message history.
+   */
+  goalCondition?: string
+}
+
+export const AgentOutputSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('structuredOutput'),
+    value: z.record(z.string(), jsonValueSchema).or(z.null()),
+  }),
+  z.object({
+    type: z.literal('lastMessage'),
+    value: z.array(z.custom<Message>()), // Array of assistant and tool messages from the last turn, including tool results
+  }),
+  z.object({
+    type: z.literal('allMessages'),
+    value: z.array(z.custom<Message>()),
+  }),
+  z.object({
+    type: z.literal('error'),
+    message: z.string(),
+    statusCode: z.number().optional(),
+    error: z.string().optional(),
+    countryCode: z.string().optional(),
+    countryBlockReason: z.string().optional(),
+    ipPrivacySignals: z.array(z.string()).optional(),
+  }),
+])
+export type AgentOutput = z.infer<typeof AgentOutputSchema>
+
+export const AgentTemplateTypeList = [
+  // ECHO agents
+  'thinker',
+  'scout',
+  'verifier',
+  'forge',
+  'recorder',
+  'scribe',
+
+  // Personas (used by agent runtime for mode selection)
+  'ask',
+  'planner',
+  'dry_run',
+
+  // Infrastructure agents
+  'file_explorer',
+  'researcher',
+  'code_searcher',
+] as const
+type UnderscoreToDash<S extends string> = S extends `${infer L}_${infer R}`
+  ? `${L}-${UnderscoreToDash<R>}` // recurse on the remainder
+  : S
+export const AgentTemplateTypes = Object.fromEntries(
+  AgentTemplateTypeList.map((name) => [name, name.replaceAll('_', '-')]),
+) as { [K in (typeof AgentTemplateTypeList)[number]]: UnderscoreToDash<K> }
+const agentTemplateTypeSchema = z.enum(AgentTemplateTypeList)
+// Allow dynamic agent types by extending the base enum with string
+export type AgentTemplateType =
+  z.infer<typeof agentTemplateTypeSchema> | (string & {})
+
+export type SessionState = {
+  fileContext: ProjectFileContext
+  mainAgentState: AgentState
+}
+
+export function getInitialAgentState(): AgentState {
+  return {
+    agentId: 'main-agent',
+    agentType: null,
+    agentContext: {},
+    ancestorRunIds: [],
+    runId: undefined,
+    subagents: [],
+    childRunIds: [],
+    messageHistory: [],
+    stepsRemaining: MAX_AGENT_STEPS_DEFAULT,
+    creditsUsed: 0,
+    directCreditsUsed: 0,
+    output: undefined,
+    parentId: undefined,
+    systemPrompt: '',
+    toolDefinitions: {},
+    contextTokenCount: 0,
+    fsmPhase: 'idle',
+    iterationCount: 0,
+  }
+}
+export function getInitialSessionState(
+  fileContext: ProjectFileContext,
+): SessionState {
+  return {
+    mainAgentState: getInitialAgentState(),
+    fileContext,
+  }
+}

package/common/src/types/skill.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod/v4'
+
+import {
+  SKILL_NAME_MAX_LENGTH,
+  SKILL_NAME_REGEX,
+  SKILL_DESCRIPTION_MAX_LENGTH,
+} from '../constants/skills'
+
+/**
+ * Zod schema for skill frontmatter metadata.
+ */
+export const SkillMetadataSchema = z.record(z.string(), z.string())
+
+/**
+ * Zod schema for skill frontmatter (parsed from YAML).
+ */
+export const SkillFrontmatterSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .max(SKILL_NAME_MAX_LENGTH)
+    .regex(
+      SKILL_NAME_REGEX,
+      'Name must be lowercase alphanumeric with single hyphen separators',
+    ),
+  description: z.string().min(1).max(SKILL_DESCRIPTION_MAX_LENGTH),
+  license: z.string().optional(),
+  metadata: SkillMetadataSchema.optional(),
+})
+
+export type SkillFrontmatter = z.infer<typeof SkillFrontmatterSchema>
+
+/**
+ * Full skill definition including content and source path.
+ */
+export const SkillDefinitionSchema = z.object({
+  /** Skill name (must match directory name) */
+  name: z.string(),
+  /** Short description for agent discovery */
+  description: z.string(),
+  /** Optional license */
+  license: z.string().optional(),
+  /** Optional key-value metadata */
+  metadata: SkillMetadataSchema.optional(),
+  /** Full SKILL.md content (including frontmatter) */
+  content: z.string(),
+  /** Source file path */
+  filePath: z.string(),
+})
+
+export type SkillDefinition = z.infer<typeof SkillDefinitionSchema>
+
+/**
+ * Collection of skills keyed by skill name.
+ */
+export type SkillsMap = Record<string, SkillDefinition>

package/common/src/types/source.ts

@@ -0,0 +1,11 @@
+/**
+ * Represents a source of data.
+ *
+ * By default, can be a value or a promise.
+ *
+ * In the case that the type is a not function itself, this can also be a function that returns the value or promise.
+ */
+export type Source<T> =
+  | T
+  | Promise<T>
+  | (T extends (...args: unknown[]) => unknown ? never : () => T | Promise<T>)

package/common/src/types/spawn.ts

@@ -0,0 +1,13 @@
+import type { ChildProcess, SpawnOptions } from 'child_process'
+
+/**
+ * Spawn function for running shell commands.
+ *
+ * Compatible with `child_process.spawn` from Node.js.
+ * Returns ChildProcess to support full streaming capabilities (stdin, stdout, stderr).
+ */
+export type SavantCodeSpawn = (
+  command: string,
+  args?: readonly string[],
+  options?: SpawnOptions,
+) => ChildProcess