vivi

A small, headless TypeScript tool-calling loop. @ayayaq/vivi provides messages, provider adapters, agent turns, and optional trusted tools. Your host owns approvals, credentials, storage, filesystem policy, and UI. Node.js 22+, ESM and CommonJS. Only the optional skills module loads the maintained YAML parser dependency.

Public npm latest was verified as 0.17.0 on 2026-11-01. Published 0.17.0 adds generic OpenAI request projection and safe error details, plus the OpenRouter reasoning-replay fix. Hosts still own authentication, storage and approval policy; core does not add ChatGPT sign-in or Skip permissions UI. See the release provenance and RELEASING.md.

Patch 0.17.1 is prepared separately and is not yet published. It recognizes valid SSE with missing/incorrect media types and improves safe diagnostics for other responses. Authentication stays host-owned; the actual reported ChatGPT session remains unverified. Use the frozen reviewed archive and receipt for publication, not a repack of this checkout. See RELEASING.md.

Optional context management (since 0.14.0)

The root API adds full projected-request occupancy, explicit known/unknown capacities, measureContext, manual/automatic portable compaction, separate source-bound checkpoints, and one classified-overflow retry. Canonical raw history and tool/approval evidence stay unchanged. Hosts own durable checkpoint storage and UI; extra summary usage is separate. See CONTEXT.md. This feature is available in published 0.14.0.

Workspace instructions and tool images (available in 0.16.0)

Fresh host-owned getContextPrefix messages are measured before each dispatch without entering canonical history. Optional image-bearing tool results carry immutable snapshot references to vision-capable provider adapters; hosts retain file permissions and storage. See fresh prefixes and tool image observations. No attachment command or host adoption is included.

Optional clarification questions (since 0.12.0)

The opt-in @ayayaq/vivi/extensions/questions subpath offers a renderer-neutral request_user_input tool for 1–3 questions, choices, free text and explicit skip/cancel. A host callback collects actual human input; without one, no tool is advertised. Answers are ordinary tool results and never authorize actions or change approval modes. Both normal and Plan-mode hosts can use the extension under their own tool policy. See the question host contract and offline example. This addition is available from published 0.12.0; hosts adopt it under their own policy.

Optional queued-message steering is available in 0.16.0. Hosts own queue acknowledgement and force-send cancellation; see STEERING.md.

Optional decision review

This module is published in verified stable 0.7.0 and absent from immutable 0.6.0. Exact registry bytes and clean Node 22/24 consumers are verified; host adoption follows separately.

@ayayaq/vivi/decisions provides frozen exact-action snapshots, allow / ask / deny recommendations, and dedicated OpenAI Decisions / OpenRouter Jev adapters. It never grants permissions or executes tools. Host rules, eligibility, privacy, manual review, and audit stay with your application. See DECISIONS.md and the offline examples/decisions.mjs before adopting it.

Verified 0.8.0 adds optional host-prepared effect metadata and pure review routing on the same subpath. Host adoption remains separately reviewed; see the contract.

Install

The latest verified public npm release is 0.17.0:

npm install --save-exact @ayayaq/[email protected]

The registry archive matches the preserved release packet exactly. Its source, metadata patch, hashes and reproducibility limits are recorded in the release provenance. Host adoption remains a separate integration decision. Hosts retain connections, processes, credentials, actual sends and UI. See MCP.md and RELEASING.md.

0.10.0 also adds owned scopes, /events session snapshots and /events/stream ordered accepted-message replay. Its registry bytes are verified and unchanged. See the host commit and bounded replay contract.

Optional model capabilities

The @ayayaq/vivi/providers/deepseek adapter (since 0.15.0) supports ordinary DeepSeek Chat Completions independently of web retrieval and decision review, with native all-turn reasoning retention and catalog-derived capabilities. See the DeepSeek host contract.

The optional @ayayaq/vivi/providers/models subpath is published in verified registry 0.4.0 and absent from immutable 0.3.0. Hosts can adopt it through separate reviewed changes that preserve their documented capability coverage and selection behavior.

import { normalizeModelCapabilities, reasoningSelectionSupport } from '@ayayaq/vivi/providers/models'

const capabilities = normalizeModelCapabilities({
  apiVersion: 1,
  provider: 'openai',
  protocol: 'responses',
  model: { id: 'gpt-5.1' }
})
console.log(capabilities.tools) // supported
console.log(reasoningSelectionSupport(capabilities, { mode: 'disabled' })) // supported

Normalization is pure and endpoint-aware. It preserves exact IDs and supported/unsupported/unknown states, including separate reasoning, effort selection, explicit disable, and mandatory status. Default means no override, independently of explicit disable. No models are fetched or selected, and no request is changed. Hosts retain credentials, catalog fetching/cache, defaults, moderation, and access policy. The contract and provenance explains the bounded seed registry, paired host evidence, and the release/adoption gate.

Optional shared memory (published 0.5.0)

The optional @ayayaq/vivi/extensions/memory module extracts the desktop v1 bounded memory service, codec, revisions, user-level context formatter and tool guidance. It is published in verified 0.5.0 and absent from immutable 0.4.0. Hosts supply atomic persistence/recovery and mandatory tool-policy callbacks; approvals, planning mode, operation admission/drain, app-wide store paths and multi-process locking remain host-owned. See the memory contract and offline policy example. No host integration or session-note migration is included.

Optional instruction-only skills (published 0.6.0)

The optional @ayayaq/vivi/extensions/skills module reads ordinary Agent Skills SKILL.md files, advertises a compact per-turn catalog, and loads instructions/resources on demand. It includes an original read-only skill creator and an optional SKILL.md-only save tool behind exact-content host approval and revision-checked persistence. Hosts choose approved sources, own their app-wide stores and apply existing permissions. No scripts/plugins execute, no workspace is scanned, and no current turn hot-reloads. This module is published in verified 0.6.0 and absent from immutable 0.5.0. Desktop/CLI adoption remains separately reviewed. See the format and host contract and offline example.

Small headless example

This example needs no terminal framework, app, provider key, or network request:

import { runAgent } from '@ayayaq/vivi'
import { createToolRegistry } from '@ayayaq/vivi/extensions'
import { calculatorExtension } from '@ayayaq/vivi/extensions/calculator'

const registry = createToolRegistry([calculatorExtension])
const result = await runAgent({
  provider: { async generate({ messages }) {
    const answer = messages.find(message => message.kind === 'tool_result')
    return answer
      ? { content: answer.content, toolCalls: [] }
      : { content: '', toolCalls: [
        { id: 'calc-1', name: 'calculate', arguments: { expression: '2*(3+4)' } }
      ] }
  } },
  messages: [{ kind: 'message', role: 'user', content: 'Calculate 2*(3+4)' }],
  tools: registry.tools,
  executeTool: registry.executeTool
})
console.log(result.status, result.content) // completed {"result":14}

Extension code runs in-process and is trusted. Registration is not a security sandbox; each host enforces its own permissions and approvals. Real provider adapters are available through @ayayaq/vivi/providers/openai and @ayayaq/vivi/providers/openrouter.

Develop and learn more

npm ci
npm run check

Checks use fake providers and HTTP, build both module formats, and install packed consumers. The package includes builds, declarations, source, examples, and documentation; installation runs no build script.

• API and host integration: contracts, usage, providers, history, and extensions
• Optional web search and fetch: separate host-controlled retrieval and DeepSeek adapter
• Runnable headless example and inventory policy example
• Changelog, release status and workflow, shared-use audit
• Apache-2.0: LICENSE, NOTICE, origin and attribution

Dependency policy

Source development requires npm >=11.17.0. Read the seven-day dependency cooldown before installing or updating dependencies.