nebula-ai-core 0.1.0

package/src/permission/service.ts

@@ -0,0 +1,191 @@
+import { detectDangerousCommand } from './dangerous'
+
+/**
+ * Permission system core. Three resolution modes:
+ *   - 'strict': dangerous patterns always denied, no prompt
+ *   - 'prompt': dangerous patterns prompt the user once / for the session / deny
+ *   - 'off' (YOLO): dangerous patterns allowed silently
+ *
+ * Approvals are scoped per-session via a Set of allowed pattern keys. The
+ * service is UI-agnostic; chat.tsx wires `setPrompter()` to its own modal.
+ * In headless contexts (tests, scripted CLI) the default prompter denies.
+ */
+export type PermissionMode = 'strict' | 'prompt' | 'off'
+export type PermissionDecision = 'allow-once' | 'allow-session' | 'deny'
+
+export interface PermissionRequest {
+  kind:
+    | 'shell.run'
+    | 'shell.process'
+    | 'code.execute'
+    | 'fs.write'
+    | 'fs.patch'
+    | 'chain.send'
+    | 'chain.swap'
+    | 'chain.write'
+  command?: string
+  path?: string
+  /** For value-moving tx tools: human-readable amount (e.g. "0.05 Mantle"). */
+  amount?: string
+  /** For value-moving tx tools: 0x recipient or contract address. */
+  recipient?: string
+  /** For value-moving tx tools: token symbol. */
+  token?: string
+  /** Description of why approval is needed (e.g. "delete in root path"). */
+  reason: string
+  /**
+   * Deterministic policy floor: when true, the on-chain policy engine has
+   * flagged this action as material-risk and it MUST be approved by a human
+   * regardless of the session permission mode — even under YOLO. In `strict`
+   * mode a forced request is denied outright. This is how fund controls are
+   * enforced in code rather than left to the model (CLAUDE.md).
+   */
+  force?: boolean
+}
+
+export type PermissionPrompter = (req: PermissionRequest) => Promise<PermissionDecision>
+
+export interface PermissionServiceOpts {
+  mode: PermissionMode
+  prompter?: PermissionPrompter
+}
+
+const DEFAULT_DENY_PROMPTER: PermissionPrompter = async () => 'deny'
+
+export class PermissionService {
+  private mode: PermissionMode
+  private prompter: PermissionPrompter
+  private readonly sessionAllowed = new Set<string>()
+
+  constructor(opts: PermissionServiceOpts) {
+    this.mode = opts.mode
+    this.prompter = opts.prompter ?? DEFAULT_DENY_PROMPTER
+  }
+
+  setMode(mode: PermissionMode): void {
+    this.mode = mode
+  }
+
+  setPrompter(p: PermissionPrompter): void {
+    this.prompter = p
+  }
+
+  isYolo(): boolean {
+    return this.mode === 'off'
+  }
+
+  getMode(): PermissionMode {
+    return this.mode
+  }
+
+  /**
+   * Resolve a permission for a tool call.
+   *   - `force` (policy floor): material-risk per the on-chain policy — prompt
+   *     beneath any mode; deny in strict; even YOLO must approve.
+   *   - YOLO ('off'): otherwise always allow.
+   *   - Strict: dangerous pattern => deny, otherwise allow.
+   *   - Prompt: dangerous pattern OR shell.run => consult `prompter`,
+   *     honour session-allow on subsequent identical signatures.
+   */
+  async resolve(req: PermissionRequest): Promise<{
+    allowed: boolean
+    reason?: string
+    via: 'yolo' | 'allow' | 'session-allow' | 'once' | 'deny' | 'strict-deny'
+  }> {
+    const dangerous = req.command ? detectDangerousCommand(req.command) : { match: false as const }
+
+    // Signature for session-allow tracking. When the request matched a
+    // dangerous pattern, key on the PATTERN (e.g. "delete in root path") so
+    // the user's "allow session" covers every match of the same pattern for
+    // the rest of the session, not just the literal command.
+    const sigKey = dangerous.match ? this.signature(req, dangerous.key) : this.signature(req)
+    if (this.sessionAllowed.has(sigKey)) {
+      return { allowed: true, via: 'session-allow' }
+    }
+
+    // Deterministic policy floor: a `force`-flagged action is material-risk per
+    // the on-chain policy engine and requires human approval BENEATH the
+    // session mode — even under YOLO. strict denies it outright; otherwise it
+    // consults the prompter regardless of mode. Fund controls live in code.
+    if (req.force) {
+      if (this.mode === 'strict') {
+        return {
+          allowed: false,
+          reason: `${req.reason} (policy: approval required, denied in strict mode)`,
+          via: 'strict-deny',
+        }
+      }
+      const decision = await this.prompter(req)
+      return this.applyDecision(decision, sigKey)
+    }
+
+    if (this.mode === 'off') return { allowed: true, via: 'yolo' }
+
+    // Value-moving on-chain tools: ALWAYS prompt in `prompt` mode regardless
+    // of dangerous-pattern match (which is regex-based and doesn't fire here).
+    // In `strict` mode they're denied — strict means "no autonomous spending".
+    const isValueMoving =
+      req.kind === 'chain.send' || req.kind === 'chain.swap' || req.kind === 'chain.write'
+    if (this.mode === 'strict') {
+      if (isValueMoving) {
+        return {
+          allowed: false,
+          reason: 'value-moving tx denied in strict mode',
+          via: 'strict-deny',
+        }
+      }
+      if (dangerous.match) {
+        return { allowed: false, reason: dangerous.description, via: 'strict-deny' }
+      }
+      return { allowed: true, via: 'allow' }
+    }
+
+    // mode === 'prompt': dangerous patterns + every shell-class invocation
+    // + every value-moving on-chain tx consult the prompter.
+    if (dangerous.match) {
+      const decision = await this.prompter({ ...req, reason: dangerous.description })
+      return this.applyDecision(decision, sigKey)
+    }
+    if (
+      req.kind === 'shell.run' ||
+      req.kind === 'shell.process' ||
+      req.kind === 'code.execute' ||
+      isValueMoving
+    ) {
+      const decision = await this.prompter(req)
+      return this.applyDecision(decision, sigKey)
+    }
+    return { allowed: true, via: 'allow' }
+  }
+
+  /**
+   * Approve a fs.write/fs.patch path explicitly (skip prompter). Tests use
+   * this; chat.tsx wires it through the approval modal.
+   */
+  approveSession(req: PermissionRequest): void {
+    this.sessionAllowed.add(this.signature(req))
+  }
+
+  private applyDecision(
+    decision: PermissionDecision,
+    sigKey: string,
+  ): { allowed: boolean; reason?: string; via: 'session-allow' | 'once' | 'deny' } {
+    if (decision === 'allow-session') {
+      this.sessionAllowed.add(sigKey)
+      return { allowed: true, via: 'session-allow' }
+    }
+    if (decision === 'allow-once') return { allowed: true, via: 'once' }
+    return { allowed: false, reason: 'rejected in approval modal', via: 'deny' }
+  }
+
+  private signature(req: PermissionRequest, dangerousKey?: string): string {
+    // For dangerous-pattern matches, key on the pattern type ("delete in
+    // root path", "recursive delete", ...) so allow-session generalises
+    // across every command that triggers the same pattern. Without this,
+    // each unique rm path was a fresh decision.
+    if (dangerousKey) return `${req.kind}|dangerous:${dangerousKey}`
+    return [req.kind, req.command ?? '', req.path ?? '', req.recipient ?? '', req.token ?? ''].join(
+      '|',
+    )
+  }
+}

package/src/plugins/context.ts

@@ -0,0 +1,225 @@
+import type { ClaudeAgent } from '../claude-plugins/types'
+import type { Listener } from '../events/listeners'
+import type { SandboxBackend } from '../sandbox/types'
+import type { ToolRegistry } from '../tools/registry'
+import type { ToolDef, ToolSchema } from '../tools/types'
+import type { HookBus, HookHandler, HookName } from './hooks'
+
+/** Vision inputs for image-capable models (provider-agnostic). */
+export type VisionInferImage = { bytes: Uint8Array; mediaType: string }
+export type VisionInferInput = {
+  prompt: string
+  images: VisionInferImage[]
+  maxOutputTokens?: number
+}
+export type VisionInferResult = {
+  content: string
+  model?: string | null
+  usage?: {
+    promptTokens?: number
+    completionTokens?: number
+    totalTokens?: number
+    cachedTokens?: number
+  }
+  finishReason?: string
+}
+export type VisionInferFn = (input: VisionInferInput) => Promise<VisionInferResult>
+
+/**
+ * Factory chat.tsx supplies for `delegate.task` to spin up a sub-brain. The
+ * implementation typically wraps `OGComputeBrain` with a custom system prompt
+ * + restricted tool surface.
+ */
+export interface DelegateBrainFactoryOpts {
+  systemPrompt: string
+  tools: ToolSchema[]
+}
+
+export interface DelegateBrainTurn {
+  content: string | null
+  finishReason?: string
+  toolCalls?: Array<{ id: string; name: string; args: unknown }>
+  usage?: {
+    totalTokens?: number
+    cachedTokens?: number
+    promptTokens?: number
+    completionTokens?: number
+  }
+}
+
+export interface DelegateBrainHandle {
+  infer(input: {
+    event: { id: string; source: 'stdin'; payload: { label: string; data: string }; ts: number }
+  }): Promise<DelegateBrainTurn>
+}
+
+export type DelegateBrainFactory = (opts: DelegateBrainFactoryOpts) => Promise<DelegateBrainHandle>
+
+/**
+ * Context handed to a plugin's `register(ctx)` function. Plugins use this
+ * to contribute tools, listeners, and lifecycle hooks; we deliberately
+ * keep the surface tiny so future plugin features extend it without
+ * breaking existing native plugins.
+ */
+export interface PluginContext {
+  registerTool: (def: ToolDef) => void
+  registerListener: (l: Listener) => void
+  addHook: <TIn = unknown, TOut = void>(name: HookName, fn: HookHandler<TIn, TOut>) => void
+  /** Network the agent is configured for. */
+  network: 'mantle-mainnet' | 'mantle-testnet'
+  /** Agent state directory (`~/.nebula/agents/<id>/`). */
+  agentDir: string
+  /** Per-agent unique id (matches `iNFTAgentId(...)` for non-stub agents). */
+  agentId: string
+  /** Absolute path to ~/.nebula/config.ts. Plugins that persist user-level state write here. */
+  configPath: string
+  /** Imports surface from config (e.g. claudeCode toggle for skills + MCP discovery). */
+  imports: { claudeCode: boolean }
+  /**
+   * Mutable cell holding the user-disabled skill ids. Plugin tools that
+   * change the list update this, and the chat rebuilds the skill index from
+   * the current value next turn.
+   */
+  skillsDisabled: { current: string[] }
+  /** Path to the agent's activity log (~/.nebula/agents/<id>/activity.jsonl). */
+  activityLogPath: string
+  /** Workspace cwd. Used by tools that spawn subprocesses. */
+  workspaceRoot: string
+  /**
+   * Sub-brain factory (Phase 9.3 delegate.task). Chat.tsx supplies a closure
+   * that builds an OGComputeBrain with broker creds. Tools without a brain
+   * dependency ignore this.
+   */
+  delegateFactory?: DelegateBrainFactory
+  /** Claude Code agents discovered from the local plugin cache. */
+  claudeAgents: ClaudeAgent[]
+  /** Whether the configured brain supports image inputs. */
+  brainSupportsVision: boolean
+  /** Brain model label (string). Surfaces in tool error messages. */
+  brainModelLabel: string | null
+  /**
+   * v0.11 vision routing: when set, vision.analyze + browser.vision call
+   * this function (backed by a BrokerPool entry pinned to the configured
+   * vision provider). Null when no vision provider is configured.
+   */
+  visionInfer?: VisionInferFn | null
+  /**
+   * Phase 9.5: sandbox backend wrapping every spawn() in shell.run / code.execute /
+   * shell.process_start. Optional for back-compat: legacy callers + tests that
+   * don't supply one get a LocalBackend (passthrough) inside the plugin.
+   */
+  sandbox?: SandboxBackend
+  /**
+   * Phase 7 side-band runtime context for plugin-comms. Opaque to core; the
+   * plugin reads its concrete shape via a typed cast. Holding the field as
+   * `unknown` keeps core free of a back-edge to the comms package.
+   */
+  comms?: unknown
+  /**
+   * Phase 10 side-band runtime context for plugin-onchain. Same opaque
+   * pattern as `comms`.
+   */
+  onchain?: unknown
+  /**
+   * Phase 12 side-band runtime context for plugin-telegram. Same opaque
+   * pattern: chat.tsx (local) or build-runtime.ts (sandbox) builds the typed
+   * `TelegramRuntimeContext` and passes it; the plugin casts on read.
+   */
+  telegram?: unknown
+}
+
+export interface NativePlugin {
+  name: string
+  register: (ctx: PluginContext) => void | Promise<void>
+}
+
+export interface PluginLoadResult {
+  loaded: string[]
+  errors: { plugin: string; error: string }[]
+}
+
+export interface PluginLoaderDeps {
+  tools: ToolRegistry
+  hooks: HookBus
+  listeners: { register: (l: Listener) => void }
+  agentDir: string
+  agentId: string
+  network: 'mantle-mainnet' | 'mantle-testnet'
+  configPath: string
+  imports: { claudeCode: boolean }
+  skillsDisabled: { current: string[] }
+  activityLogPath: string
+  workspaceRoot: string
+  delegateFactory?: DelegateBrainFactory
+  claudeAgents?: ClaudeAgent[]
+  brainSupportsVision?: boolean
+  brainModelLabel?: string | null
+  visionInfer?: VisionInferFn | null
+  /** Phase 9.5 sandbox backend, propagated to plugin context. Optional. */
+  sandbox?: SandboxBackend
+  /** Phase 7 side-band runtime context for plugin-comms. Opaque to core. */
+  comms?: unknown
+  /** Phase 10 side-band runtime context for plugin-onchain. Opaque to core. */
+  onchain?: unknown
+  /** Phase 12 side-band runtime context for plugin-telegram. Opaque to core. */
+  telegram?: unknown
+  /**
+   * Resolver for `name` → ESM module path. Defaults to dynamic import of
+   * `nebula-ai-plugin-<name>`. Tests pass a stub.
+   */
+  resolve?: (name: string) => Promise<{ default?: NativePlugin } & Partial<NativePlugin>>
+}
+
+export async function loadPlugins(
+  names: readonly string[],
+  deps: PluginLoaderDeps,
+): Promise<PluginLoadResult> {
+  const loaded: string[] = []
+  const errors: PluginLoadResult['errors'] = []
+  const ctx: PluginContext = {
+    registerTool: def => deps.tools.register(def),
+    registerListener: l => deps.listeners.register(l),
+    addHook: (name, fn) => deps.hooks.add(name, fn),
+    network: deps.network,
+    agentDir: deps.agentDir,
+    agentId: deps.agentId,
+    configPath: deps.configPath,
+    imports: deps.imports,
+    skillsDisabled: deps.skillsDisabled,
+    activityLogPath: deps.activityLogPath,
+    workspaceRoot: deps.workspaceRoot,
+    delegateFactory: deps.delegateFactory,
+    claudeAgents: deps.claudeAgents ?? [],
+    brainSupportsVision: deps.brainSupportsVision ?? false,
+    brainModelLabel: deps.brainModelLabel ?? null,
+    visionInfer: deps.visionInfer ?? null,
+    sandbox: deps.sandbox,
+    comms: deps.comms,
+    onchain: deps.onchain,
+    telegram: deps.telegram,
+  }
+  for (const name of names) {
+    try {
+      const mod = deps.resolve
+        ? await deps.resolve(name)
+        : ((await import(`nebula-ai-plugin-${name}`)) as {
+            default?: NativePlugin
+          } & Partial<NativePlugin>)
+      const plugin: NativePlugin | undefined =
+        mod.default && 'register' in mod.default
+          ? mod.default
+          : 'register' in mod && typeof mod.register === 'function'
+            ? (mod as unknown as NativePlugin)
+            : undefined
+      if (!plugin) {
+        errors.push({ plugin: name, error: 'no exported register(ctx)' })
+        continue
+      }
+      await plugin.register(ctx)
+      loaded.push(name)
+    } catch (e) {
+      errors.push({ plugin: name, error: (e as Error).message ?? String(e) })
+    }
+  }
+  return { loaded, errors }
+}

package/src/plugins/hooks.ts

@@ -0,0 +1,81 @@
+import type { ToolCall, ToolResult } from '../tools/types'
+
+/**
+ * Lifecycle hook surface. Plugins register handlers via `ctx.addHook(name, fn)`.
+ * Hooks run in registration order; pre-* hooks may return a replacement
+ * payload to mutate the input, while post-* hooks observe only.
+ *
+ * Phase 9.0 wires `pre_tool_call` + `post_tool_call` into the chat loop.
+ * The other 8 names exist as no-op stubs so plugins can target them now and
+ * future phases (LLM call, session lifecycle) can light them up without
+ * breaking the contract.
+ */
+export type HookName =
+  | 'pre_tool_call'
+  | 'post_tool_call'
+  | 'pre_llm_call'
+  | 'post_llm_call'
+  | 'pre_api_request'
+  | 'post_api_request'
+  | 'on_session_start'
+  | 'on_session_end'
+  | 'on_session_finalize'
+  | 'on_session_reset'
+
+export interface PreToolCallContext {
+  call: ToolCall
+}
+
+export interface PreToolCallResult {
+  /** Replacement call (e.g. permission injection edits args). undefined = no change. */
+  call?: ToolCall
+  /** If set, short-circuit dispatch with this result. */
+  short?: ToolResult
+}
+
+export interface PostToolCallContext {
+  call: ToolCall
+  result: ToolResult
+}
+
+export type HookHandler<TIn, TOut = void> = (
+  ctx: TIn,
+) => Promise<TOut | undefined> | TOut | undefined
+
+export class HookBus {
+  private readonly handlers = new Map<HookName, HookHandler<unknown, unknown>[]>()
+
+  add<TIn = unknown, TOut = void>(name: HookName, fn: HookHandler<TIn, TOut>): void {
+    const list = this.handlers.get(name) ?? []
+    list.push(fn as HookHandler<unknown, unknown>)
+    this.handlers.set(name, list)
+  }
+
+  /**
+   * Run pre-tool-call hooks in order. Each handler may return a replacement
+   * call or a short-circuit result. The first short-circuit wins. Returns the
+   * effective call + optional short-circuit.
+   */
+  async runPreToolCall(input: PreToolCallContext): Promise<PreToolCallResult> {
+    let current: ToolCall = input.call
+    const fns = this.handlers.get('pre_tool_call') ?? []
+    for (const fn of fns) {
+      const out = (await fn({ call: current })) as PreToolCallResult | undefined
+      if (!out) continue
+      if (out.short) return { short: out.short, call: current }
+      if (out.call) current = out.call
+    }
+    return { call: current }
+  }
+
+  async runPostToolCall(input: PostToolCallContext): Promise<void> {
+    const fns = this.handlers.get('post_tool_call') ?? []
+    for (const fn of fns) {
+      try {
+        await fn(input)
+      } catch {
+        // Post hooks must never break the chat loop.
+      }
+    }
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,24 @@
+export {
+  HookBus,
+  type HookName,
+  type HookHandler,
+  type PreToolCallContext,
+  type PreToolCallResult,
+  type PostToolCallContext,
+} from './hooks'
+export {
+  loadPlugins,
+  type PluginContext,
+  type NativePlugin,
+  type PluginLoadResult,
+  type PluginLoaderDeps,
+  type DelegateBrainFactory,
+  type DelegateBrainFactoryOpts,
+  type DelegateBrainHandle,
+  type DelegateBrainTurn,
+  type VisionInferFn,
+  type VisionInferInput,
+  type VisionInferImage,
+  type VisionInferResult,
+} from './context'
+export { makeToolSearchTool, type ToolSearchArgs } from './tool-search'

package/src/plugins/tool-search.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+import type { ToolRegistry } from '../tools/registry'
+import type { ToolDef } from '../tools/types'
+import { coerceInt } from '../tools/zod-helpers'
+import { zodToJsonSchema } from '../tools/zod-schema'
+
+const ToolSearchSchema = z.object({
+  query: z.string().min(1, 'query is required'),
+  max_results: coerceInt.refine(n => n > 0 && n <= 20, 'max_results must be 1..20').optional(),
+})
+
+export type ToolSearchArgs = z.infer<typeof ToolSearchSchema>
+
+/**
+ * `tool.search` meta-tool: brain calls this to hydrate deferred tool
+ * schemas. Mirrors Claude Code's ToolSearch surface, accepts either an
+ * explicit `select:foo,bar` query or a free-text keyword query.
+ */
+export function makeToolSearchTool(registry: ToolRegistry): ToolDef<ToolSearchArgs> {
+  return {
+    name: 'tool.search',
+    description:
+      'Look up deferred tool schemas. Use `select:name1,name2` to fetch by name, or free-text keywords (e.g., "filesystem read") to search descriptions and hints. Returns matching tools with their full parameter schema; the brain can immediately call them next turn.',
+    alwaysLoad: true,
+    searchHint: 'meta search deferred tools schemas',
+    schema: ToolSearchSchema,
+    handler: args => {
+      const max = args.max_results ?? 5
+      const matches = registry.search(args.query, max)
+      const schemas = matches.map(t => {
+        registry.unlock(t.name)
+        return {
+          name: t.name,
+          description: t.description,
+          parameters: t.parametersOverride ?? zodToJsonSchema(t.schema),
+          searchHint: t.searchHint,
+        }
+      })
+      return {
+        ok: true,
+        data: {
+          query: args.query,
+          matched: schemas.length,
+          tools: schemas,
+        },
+      }
+    },
+  }
+}

package/src/public/card.ts

@@ -0,0 +1,67 @@
+import matter from 'gray-matter'
+
+export interface CardFrontmatter {
+  /** Display name, e.g. "Alice". */
+  name: string
+  /** Short one-line bio, <= 140 chars. */
+  bio?: string
+  /** Skills / domains the agent is competent in. */
+  skills?: string[]
+  /** Endpoints the agent exposes (URLs). */
+  endpoints?: string[]
+  /** Avatar: either a Mantle Storage CID or an absolute URL. */
+  avatar?: string
+  /** Fully-qualified .0g subname, e.g. "alice.nebula.0g". */
+  subname?: string
+  /** iNFT pointer, CAIP-10-ish: eip155:<chainId>:<contract>:<tokenId> */
+  inft?: string
+  [key: string]: unknown
+}
+
+export interface Card {
+  frontmatter: CardFrontmatter
+  body: string
+}
+
+const DEFAULT_CARD: Card = {
+  frontmatter: {
+    name: '',
+    bio: '',
+    skills: [],
+    endpoints: [],
+  },
+  body: '',
+}
+
+export function parseCard(markdown: string): Card {
+  const parsed = matter(markdown)
+  const fm = (parsed.data ?? {}) as CardFrontmatter
+  if (typeof fm.name !== 'string') {
+    throw new Error('CARD.md requires a "name" frontmatter field')
+  }
+  return { frontmatter: fm, body: parsed.content ?? '' }
+}
+
+export function renderCard(card: Card): string {
+  return matter.stringify(card.body, card.frontmatter as Record<string, unknown>)
+}
+
+export function emptyCard(): Card {
+  return {
+    frontmatter: { ...DEFAULT_CARD.frontmatter },
+    body: DEFAULT_CARD.body,
+  }
+}
+
+/** Map a Card to the text-record key/value pairs we publish to .0g. */
+export function cardToTextRecords(card: Card, agentEoa?: string): Record<string, string> {
+  const rec: Record<string, string> = {}
+  const fm = card.frontmatter
+  if (agentEoa) rec.address = agentEoa
+  if (fm.bio) rec['agent:bio'] = fm.bio
+  if (fm.skills?.length) rec['agent:skills'] = fm.skills.join(',')
+  if (fm.endpoints?.length) rec['agent:endpoints'] = fm.endpoints.join(',')
+  if (fm.avatar) rec.avatar = fm.avatar
+  if (fm.inft) rec['agent:inft'] = fm.inft
+  return rec
+}

package/src/runtime/activity.ts

@@ -0,0 +1,29 @@
+import { appendFile, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+export interface ActivityEntry {
+  ts: number
+  kind:
+    | 'wake'
+    | 'tool-call'
+    | 'tool-result'
+    | 'brain-response'
+    | 'error'
+    | 'context-compacted'
+    | 'auto-topup'
+  data: unknown
+}
+
+export class ActivityLog {
+  private dirEnsured = false
+
+  constructor(private readonly path: string) {}
+
+  async append(entry: ActivityEntry): Promise<void> {
+    if (!this.dirEnsured) {
+      await mkdir(dirname(this.path), { recursive: true })
+      this.dirEnsured = true
+    }
+    await appendFile(this.path, `${JSON.stringify(entry)}\n`, 'utf8')
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,2 @@
+export { Runtime, type RuntimeDeps } from './runtime'
+export { ActivityLog, type ActivityEntry } from './activity'