@moxxy/sdk 0.1.0

package/src/events.ts

@@ -0,0 +1,250 @@
+import type { EventId, PluginId, SessionId, SkillId, ToolCallId, TurnId } from './ids.js';
+
+export type EventSource = 'user' | 'model' | 'tool' | 'plugin' | 'system' | 'compactor';
+
+export interface EventBase {
+  readonly id: EventId;
+  readonly seq: number;
+  readonly ts: number;
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+  readonly causationId?: EventId;
+  readonly source: EventSource;
+}
+
+export interface UserPromptAttachment {
+  readonly kind: 'stdin' | 'file' | 'image' | 'audio';
+  /**
+   * Inline payload. For images this is base64-encoded bytes; for audio it
+   * is either base64-encoded bytes (when the channel hands raw audio
+   * straight through to a model with `supportsAudio`) or the transcript
+   * (when the channel pre-transcribed via the session's Transcriber).
+   * Channels SHOULD set `name` to disambiguate the two; `mediaType` is
+   * required when carrying raw audio bytes.
+   */
+  readonly content: string;
+  /** Human-readable label, e.g. the file path, `image.png`, or `voice.ogg`. */
+  readonly name?: string;
+  /** MIME type — required for images and raw audio so providers translate correctly. */
+  readonly mediaType?: string;
+}
+
+export interface UserPromptEvent extends EventBase {
+  readonly type: 'user_prompt';
+  readonly text: string;
+  readonly attachments?: ReadonlyArray<UserPromptAttachment>;
+}
+
+export interface AssistantChunkEvent extends EventBase {
+  readonly type: 'assistant_chunk';
+  readonly delta: string;
+}
+
+export interface AssistantMessageEvent extends EventBase {
+  readonly type: 'assistant_message';
+  readonly content: string;
+  readonly stopReason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'error';
+}
+
+export interface ToolCallRequestedEvent extends EventBase {
+  readonly type: 'tool_call_requested';
+  readonly callId: ToolCallId;
+  readonly name: string;
+  readonly input: unknown;
+  readonly skillContext?: SkillId;
+}
+
+export interface ToolCallApprovedEvent extends EventBase {
+  readonly type: 'tool_call_approved';
+  readonly callId: ToolCallId;
+  readonly decidedBy: 'policy' | 'resolver' | 'hook';
+  readonly mode: 'allow' | 'allow_session' | 'allow_always';
+}
+
+export interface ToolCallDeniedEvent extends EventBase {
+  readonly type: 'tool_call_denied';
+  readonly callId: ToolCallId;
+  readonly decidedBy: 'policy' | 'resolver' | 'hook';
+  readonly reason: string;
+}
+
+export interface ToolResultEvent extends EventBase {
+  readonly type: 'tool_result';
+  readonly callId: ToolCallId;
+  readonly ok: boolean;
+  readonly output?: unknown;
+  readonly error?: { message: string; kind: 'aborted' | 'threw' | 'denied' | 'timeout' };
+}
+
+export interface SkillInvokedEvent extends EventBase {
+  readonly type: 'skill_invoked';
+  readonly skillId: SkillId;
+  readonly name: string;
+  readonly reason: 'trigger_match' | 'classifier' | 'manual' | 'load_skill_tool';
+}
+
+export interface SkillCreatedEvent extends EventBase {
+  readonly type: 'skill_created';
+  readonly skillId: SkillId;
+  readonly name: string;
+  readonly path: string;
+  readonly scope: 'user' | 'project';
+  readonly originatingPrompt: string;
+}
+
+export interface PluginRegisteredEvent extends EventBase {
+  readonly type: 'plugin_registered';
+  readonly pluginId: PluginId;
+  readonly name: string;
+  readonly version: string;
+  // Keep in sync with PluginKind (plugin.ts). Inlined rather than imported to
+  // avoid an events↔plugin type cycle (dep-cruiser flags circular deps).
+  readonly kind: ReadonlyArray<
+    | 'tools'
+    | 'provider'
+    | 'mode'
+    | 'compactor'
+    | 'cache-strategy'
+    | 'view-renderer'
+    | 'tunnel-provider'
+    | 'mcp'
+    | 'cli'
+    | 'channel'
+    | 'hooks'
+    | 'agent'
+    | 'command'
+    | 'transcriber'
+  >;
+}
+
+export interface PluginUnregisteredEvent extends EventBase {
+  readonly type: 'plugin_unregistered';
+  readonly pluginId: PluginId;
+  readonly name: string;
+  readonly reason: 'reload' | 'shutdown' | 'disabled';
+}
+
+export interface ModeIterationEvent extends EventBase {
+  readonly type: 'mode_iteration';
+  readonly strategy: string;
+  readonly iteration: number;
+  readonly routing?: 'resolved' | 'unresolved' | 'synthesized';
+}
+
+export interface CompactionEvent extends EventBase {
+  readonly type: 'compaction';
+  readonly compactor: string;
+  /**
+   * Inclusive `[fromSeq, toSeq]` range of event `seq` values this summary
+   * replaces — NOT array indices. Consumers (`projectMessagesFromLog`,
+   * `estimateContextTokens`) test `event.seq` against these bounds, so a
+   * compactor MUST emit the `seq` of the first/last replaced event. (Today
+   * `seq === arrayIndex` in the primary log, but that is not guaranteed for
+   * mirrors or partial views — emit seqs to stay correct regardless.)
+   */
+  readonly replacedRange: readonly [number, number];
+  readonly summary: string;
+  readonly tokensSaved: number;
+}
+
+/**
+ * Records a turn-boundary elision step (context-on-demand). Events at or below
+ * `elidedThrough` (and not covered by a compaction) are projected as compact
+ * stubs the model can expand with the `recall` tool. The high-water mark only
+ * advances on whole-turn boundaries, so the elided prefix stays byte-stable
+ * across the inner iterations of a turn — which is what lets prompt caching
+ * keep hitting.
+ */
+export interface ElisionEvent extends EventBase {
+  readonly type: 'elision';
+  /** Inclusive seq high-water mark: events with `seq <= elidedThrough` are stubbed. */
+  readonly elidedThrough: number;
+  /** Turn-aligned [from,to] seq ranges newly stubbed by this step (informational). */
+  readonly stubbedRanges: ReadonlyArray<readonly [number, number]>;
+  /**
+   * Whether old user/assistant text turns (not just bulky tool results) are
+   * collapsed to stubs. Carried on the event so `projectMessagesFromLog` stays
+   * a pure function of the log (no need to thread config through projection).
+   * Note: even when true, conversational elision auto-disables for the session
+   * once seq-based `recall` calls reach `conversationalRecallThreshold`.
+   */
+  readonly elideConversational: boolean;
+  /**
+   * Adaptive safety: after this many `recall({ seq })` calls (the form used to
+   * recall elided TEXT turns), conversational elision turns off for the rest of
+   * the session. Carried on the event so projection decides it from the log.
+   */
+  readonly conversationalRecallThreshold: number;
+  /** Cap on total bytes of recalled content pinned verbatim below the HWM. */
+  readonly maxRecallBytes: number;
+  /** Tool names whose results are never stubbed (kept verbatim regardless of age). */
+  readonly neverElideTools: ReadonlyArray<string>;
+  readonly tokensSaved: number;
+}
+
+export interface ProviderRequestEvent extends EventBase {
+  readonly type: 'provider_request';
+  readonly provider: string;
+  readonly model: string;
+  readonly inputTokens?: number;
+}
+
+export interface ProviderResponseEvent extends EventBase {
+  readonly type: 'provider_response';
+  readonly provider: string;
+  readonly model: string;
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly cacheReadTokens?: number;
+  readonly cacheCreationTokens?: number;
+}
+
+export interface ErrorEvent extends EventBase {
+  readonly type: 'error';
+  readonly kind: 'retryable' | 'fatal' | 'tool_threw' | 'hook_failed' | 'provider_failed';
+  readonly message: string;
+  readonly sourceEventId?: EventId;
+  readonly attempt?: number;
+}
+
+export interface AbortEvent extends EventBase {
+  readonly type: 'abort';
+  readonly reason: string;
+}
+
+export interface PluginEvent extends EventBase {
+  readonly type: 'plugin_event';
+  readonly pluginId: PluginId;
+  readonly subtype: string;
+  readonly payload: unknown;
+}
+
+export type MoxxyEvent =
+  | UserPromptEvent
+  | AssistantChunkEvent
+  | AssistantMessageEvent
+  | ToolCallRequestedEvent
+  | ToolCallApprovedEvent
+  | ToolCallDeniedEvent
+  | ToolResultEvent
+  | SkillInvokedEvent
+  | SkillCreatedEvent
+  | PluginRegisteredEvent
+  | PluginUnregisteredEvent
+  | ModeIterationEvent
+  | CompactionEvent
+  | ElisionEvent
+  | ProviderRequestEvent
+  | ProviderResponseEvent
+  | ErrorEvent
+  | AbortEvent
+  | PluginEvent;
+
+export type MoxxyEventType = MoxxyEvent['type'];
+export type MoxxyEventOfType<T extends MoxxyEventType> = Extract<MoxxyEvent, { type: T }>;
+
+export type EmittedEvent = MoxxyEvent extends infer E
+  ? E extends MoxxyEvent
+    ? Omit<E, 'id' | 'seq' | 'ts'> & { ts?: number }
+    : never
+  : never;

package/src/hooks.ts

@@ -0,0 +1,54 @@
+import type { MoxxyEvent, ToolCallRequestedEvent, ToolResultEvent } from './events.js';
+import type { EventLogReader } from './log.js';
+import type { PendingToolCall } from './permission.js';
+import type { ProviderRequest } from './provider.js';
+import type { SessionId, TurnId } from './ids.js';
+
+export interface AppContext {
+  readonly sessionId: SessionId;
+  readonly cwd: string;
+  readonly log: EventLogReader;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+export interface TurnContext extends AppContext {
+  readonly turnId: TurnId;
+  readonly iteration: number;
+}
+
+export interface ToolCallContext extends TurnContext {
+  readonly call: PendingToolCall;
+}
+
+export interface ToolResultContext extends TurnContext {
+  readonly result: ToolResultEvent;
+}
+
+export type ToolCallVerdict =
+  | { readonly action: 'allow' }
+  | { readonly action: 'deny'; readonly reason: string }
+  | { readonly action: 'rewrite'; readonly input: unknown };
+
+export interface LifecycleHooks {
+  onInit?(ctx: AppContext): void | Promise<void>;
+  onTurnStart?(ctx: TurnContext): void | Promise<void>;
+  onBeforeProviderCall?(req: ProviderRequest, ctx: TurnContext): ProviderRequest | void | Promise<ProviderRequest | void>;
+  onToolCall?(ctx: ToolCallContext): ToolCallVerdict | void | Promise<ToolCallVerdict | void>;
+  onToolResult?(ctx: ToolResultContext): ToolResultEvent | void | Promise<ToolResultEvent | void>;
+  onEvent?(event: MoxxyEvent, ctx: AppContext): void | Promise<void>;
+  onTurnEnd?(ctx: TurnContext): void | Promise<void>;
+  onShutdown?(ctx: AppContext): void | Promise<void>;
+}
+
+export interface HookDispatcher {
+  dispatchInit(ctx: AppContext): Promise<void>;
+  dispatchTurnStart(ctx: TurnContext): Promise<void>;
+  dispatchBeforeProviderCall(req: ProviderRequest, ctx: TurnContext): Promise<ProviderRequest>;
+  dispatchToolCall(ctx: ToolCallContext): Promise<ToolCallVerdict>;
+  dispatchToolResult(ctx: ToolResultContext): Promise<ToolResultEvent>;
+  dispatchEvent(event: MoxxyEvent, ctx: AppContext): Promise<void>;
+  dispatchTurnEnd(ctx: TurnContext): Promise<void>;
+  dispatchShutdown(ctx: AppContext): Promise<void>;
+}
+
+export type ToolCallRequest = ToolCallRequestedEvent;

package/src/ids.ts

@@ -0,0 +1,16 @@
+declare const brand: unique symbol;
+type Brand<T, B extends string> = T & { readonly [brand]: B };
+
+export type EventId = Brand<string, 'EventId'>;
+export type TurnId = Brand<string, 'TurnId'>;
+export type ToolCallId = Brand<string, 'ToolCallId'>;
+export type SessionId = Brand<string, 'SessionId'>;
+export type PluginId = Brand<string, 'PluginId'>;
+export type SkillId = Brand<string, 'SkillId'>;
+
+export const asEventId = (s: string): EventId => s as EventId;
+export const asTurnId = (s: string): TurnId => s as TurnId;
+export const asToolCallId = (s: string): ToolCallId => s as ToolCallId;
+export const asSessionId = (s: string): SessionId => s as SessionId;
+export const asPluginId = (s: string): PluginId => s as PluginId;
+export const asSkillId = (s: string): SkillId => s as SkillId;

package/src/index.ts

@@ -0,0 +1,304 @@
+export type {
+  EventId,
+  TurnId,
+  ToolCallId,
+  SessionId,
+  PluginId,
+  SkillId,
+} from './ids.js';
+export { asEventId, asTurnId, asToolCallId, asSessionId, asPluginId, asSkillId } from './ids.js';
+
+export type {
+  EventBase,
+  EventSource,
+  MoxxyEvent,
+  MoxxyEventType,
+  MoxxyEventOfType,
+  EmittedEvent,
+  UserPromptEvent,
+  UserPromptAttachment,
+  AssistantChunkEvent,
+  AssistantMessageEvent,
+  ToolCallRequestedEvent,
+  ToolCallApprovedEvent,
+  ToolCallDeniedEvent,
+  ToolResultEvent,
+  SkillInvokedEvent,
+  SkillCreatedEvent,
+  PluginRegisteredEvent,
+  PluginUnregisteredEvent,
+  ModeIterationEvent,
+  CompactionEvent,
+  ProviderRequestEvent,
+  ProviderResponseEvent,
+  ErrorEvent,
+  AbortEvent,
+  PluginEvent,
+} from './events.js';
+
+export type { EventLogReader } from './log.js';
+
+export type {
+  RunTurnOptions,
+  SessionLogReader,
+  SessionLike,
+  SessionInfo,
+  ProviderInfo,
+  ToolInfo,
+  SkillInfo,
+  CommandInfo,
+} from './session-like.js';
+
+export type {
+  ClientSession,
+  ProvidersClientView,
+  ModesClientView,
+  ToolsClientView,
+  CommandsClientView,
+  SkillsClientView,
+  AgentsClientView,
+  TranscribersClientView,
+  RequirementsClientView,
+  PermissionsClientView,
+} from './client-session.js';
+
+export type {
+  PermissionMode,
+  PermissionDecision,
+  PermissionRule,
+  PendingToolCall,
+  PermissionContext,
+  PermissionResolver,
+} from './permission.js';
+
+export type {
+  ToolContext,
+  ToolDef,
+  ToolCompactPresentation,
+  BrokeredFs,
+  BrokeredStat,
+  BrokeredFetch,
+  BrokeredFetchInit,
+  BrokeredFetchResponse,
+  BrokeredExec,
+  BrokeredExecOpts,
+  BrokeredExecResult,
+} from './tool.js';
+
+export type {
+  FsCapability,
+  NetCapability,
+  CapabilitySpec,
+  IsolationStrength,
+  ToolIsolationSpec,
+  IsolatedToolCall,
+  Isolator,
+  HandlerModuleRef,
+} from './isolation.js';
+export { ISOLATION_RANK } from './isolation.js';
+
+export type {
+  SubagentSpec,
+  SubagentResult,
+  SubagentSpawner,
+} from './subagent.js';
+
+
+export type {
+  ContentBlock,
+  ProviderMessage,
+  ProviderRequest,
+  ProviderEvent,
+  CacheHint,
+  TokenUsage,
+  ModelDescriptor,
+  LLMProvider,
+  ProviderDef,
+  ProviderKeyValidation,
+  ProviderVault,
+  ProviderAuthContext,
+  ProviderOAuthResult,
+  ProviderOAuthStatus,
+  ProviderAuthDescriptor,
+} from './provider.js';
+export type { CacheStrategyDef, CacheStrategyContext } from './cache-strategy.js';
+export type {
+  ViewNode,
+  ViewAction,
+  ViewDoc,
+  ViewParseError,
+  ViewParseResult,
+  AttrType,
+  AttrSpec,
+  ViewTagSpec,
+  ViewRendererDef,
+} from './view-renderer.js';
+export { VIEW_PRIMITIVES, VIEW_COMPONENTS, DEFAULT_VIEW_TAGS } from './view-renderer.js';
+export type { TunnelProviderDef, TunnelHandle, TunnelOpenOptions } from './tunnel.js';
+export { isRetryableError, toFriendlyError, zodToJsonSchema, type StopReason } from './provider-utils.js';
+export {
+  MoxxyError,
+  classifyHttpStatus,
+  classifyNetworkError,
+  type MoxxyErrorCode,
+  type MoxxyErrorInit,
+} from './errors.js';
+export {
+  collectProviderStream,
+  projectMessagesFromLog,
+  projectMessages,
+  buildSystemPromptWithSkills,
+  type CollectedToolUse,
+  type StreamResult,
+  type ProjectMessagesOptions,
+  type ProjectedMessages,
+} from './mode-helpers.js';
+export { dispatchToolCall } from './tool-dispatch.js';
+
+export type { TokenBudget, CompactContext, CompactorDef } from './compactor.js';
+export { estimateContextTokens, runCompactionIfNeeded } from './compactor-helpers.js';
+export {
+  runElisionIfNeeded,
+  resolveElisionSettings,
+  type ResolvedElisionSettings,
+} from './elision-helpers.js';
+export {
+  computeElisionState,
+  toolResultStub,
+  conversationalStub,
+  toolResultBytes,
+  toolResultStubbed,
+  conversationalStubbed,
+  TINY_TURN_CHARS,
+  type ElisionState,
+} from './elision-state.js';
+export {
+  applyLazyTools,
+  buildToolIndex,
+  loadedToolNames,
+  ALWAYS_ON_TOOLS,
+  type GatedTools,
+} from './tool-gating.js';
+
+export {
+  summarizeSessionTokens,
+  summarizeSessionTokensFromEvents,
+  summarizeTokensByModel,
+  addModelTotals,
+  usageEventFields,
+  type SessionTokenSummary,
+  type ModelUsageTotals,
+} from './token-accounting.js';
+
+export type { Skill, SkillDef, SkillFrontmatter, SkillScope, SkillSchedule } from './skill.js';
+
+export type { AgentDef } from './agent.js';
+
+export type {
+  CommandDef,
+  CommandContext,
+  CommandOutput,
+  CommandHandlerResult,
+} from './command.js';
+
+export type {
+  ToolRegistry,
+  SkillRegistry,
+  PluginHostHandle,
+  ModeContext,
+  ModeDef,
+  ElisionSettings,
+  ApprovalResolver,
+  ApprovalRequest,
+  ApprovalDecision,
+  ApprovalOption,
+} from './mode.js';
+
+export type {
+  AppContext,
+  TurnContext,
+  ToolCallContext,
+  ToolResultContext,
+  ToolCallVerdict,
+  ToolCallRequest,
+  LifecycleHooks,
+  HookDispatcher,
+} from './hooks.js';
+
+export type {
+  PluginKind,
+  PluginSpec,
+  Plugin,
+  PluginManifest,
+  ResolvedPluginManifest,
+} from './plugin.js';
+
+export type {
+  Channel,
+  ChannelHandle,
+  ChannelStartOptsBase,
+  ChannelFactoryDeps,
+  ChannelDef,
+  ChannelAvailability,
+  ChannelRegistry,
+  ChannelSubcommand,
+  ChannelSubcommandContext,
+  ChannelCommandArgs,
+} from './channel.js';
+export type { EmbeddingProvider } from './embedding.js';
+export { CachedEmbeddingProvider } from './embedding-cache.js';
+
+export type {
+  RequirementKind,
+  RequirementState,
+  MoxxyRequirement,
+  RequirementIssue,
+  RequirementCheck,
+} from './requirements.js';
+
+export type {
+  Transcriber,
+  TranscriberDef,
+  TranscriptionResult,
+  TranscriptionSegment,
+  TranscribeOptions,
+} from './transcriber.js';
+
+export interface PluginLoader {
+  load(manifest: import('./plugin.js').ResolvedPluginManifest): Promise<import('./plugin.js').Plugin>;
+}
+
+export {
+  definePlugin,
+  defineTool,
+  defineProvider,
+  defineMode,
+  defineCompactor,
+  defineCacheStrategy,
+  defineViewRenderer,
+  defineTunnelProvider,
+  defineChannel,
+  definePermission,
+  defineSkill,
+  defineTranscriber,
+  defineCommand,
+  defineAgent,
+} from './define.js';
+
+export {
+  skillFrontmatterSchema,
+  pluginManifestSchema,
+  moxxyPackageSchema,
+  requirementSchema,
+  type SkillFrontmatterInput,
+  type PluginManifestInput,
+  type MoxxyPackageInput,
+} from './schemas.js';
+
+export {
+  getInstallHint,
+  type InstallHint,
+  type InstallTarget,
+} from './install-hints.js';
+
+export { z } from 'zod';

package/src/install-hints.ts

@@ -0,0 +1,43 @@
+/**
+ * Generic "how does the user install <thing> on their OS" helper, used by
+ * plugins that depend on a native binary they can't bundle themselves.
+ * Voice input wants ffmpeg; a transcription plugin might want
+ * `sox`/`opus-tools`; a doc-rendering plugin might want `pandoc`. Each
+ * caller passes either a single package name (when it's the same across
+ * platforms — the common case for widely-packaged tools) or a per-
+ * platform map for tools whose package name differs.
+ *
+ * The helper is informational. We never auto-run a system installer
+ * here: package managers prompt for sudo/UAC, and that doesn't fit a
+ * TUI cleanly. Callers render the returned command in their UI and the
+ * user runs it themselves.
+ */
+export interface InstallTarget {
+  /** Canonical package name. Used when `perPlatform` has no entry for the active OS. */
+  readonly name: string;
+  /** Override the package name on specific platforms (e.g. `winget` IDs). */
+  readonly perPlatform?: Partial<Record<NodeJS.Platform, string>>;
+}
+
+export interface InstallHint {
+  readonly command: string;
+  readonly manager: string;
+}
+
+export function getInstallHint(
+  target: string | InstallTarget,
+  platform: NodeJS.Platform = process.platform,
+): InstallHint {
+  const spec: InstallTarget = typeof target === 'string' ? { name: target } : target;
+  const pkg = spec.perPlatform?.[platform] ?? spec.name;
+  if (platform === 'darwin') {
+    return { command: `brew install ${pkg}`, manager: 'Homebrew' };
+  }
+  if (platform === 'win32') {
+    return { command: `winget install ${pkg}`, manager: 'winget' };
+  }
+  if (platform === 'linux') {
+    return { command: `sudo apt install ${pkg}`, manager: 'apt' };
+  }
+  return { command: `install ${pkg} via your platform's package manager`, manager: 'manual' };
+}