@gixcopilot/vue

AI Copilot SDK

A TypeScript-first AI Copilot & Agent SDK with a framework-independent core and React, Vue, Angular, Node.js server, and LLM provider adapters layered on top. It exists to connect application context and authorized actions to model-driven conversations without treating model output as authority.

Current status: Phase 12 — Production Platform + Ecosystem COMPLETE. Phases 1–11 are complete. Phase 12 adds Angular and Node SDKs, a CLI, multi-tenant persistence, Redis workers, model routing and usage enforcement, a management API and platform, production deployment, release tooling and a documentation portal. Packages are published to npm under the MIT license as @gixcopilot/*; the previously committed real credential was rotated and its exposure reviewed per the owner. Always check docs/PROJECT_STATUS.md for authoritative phase state; see docs/architecture/overview.md and the ADRs for the reasoning, and .claude/skills/ai-copilot-project/SKILL.md for the 12-phase roadmap.

Quick start

The Universal Existing-Project Installer is Experimental and unreleased. @gixcopilot/sdk is not published to npm yet; this is the intended flow once released (local evaluation currently requires packed packages, not a registry install). Run at an existing project's root containing package.json:

npm add @gixcopilot/sdk
npx gix init
npx gix dev

Open http://localhost:4000/__gix. init detects the project, installs missing packages for selected apps, creates missing GIX-owned bootstrap files, and prepares proposals. Review the diff, select changes, approve, then apply in Studio. Existing application source is not edited by init. Installation's postinstall only prints a hint; it never initializes the repository. See the installer guide for selection, files, server-only configuration and verification limits.

Published compatibility path

Until the SDK installer is released, the existing installer remains available for React, Vue or Angular apps (or an empty folder):

npm create @gixcopilot@latest

It detects your framework, asks a few questions, installs the SDK, adds a chat component and the dev proxy, and creates a Node copilot server (by default) that keeps the model key off the browser. Then npm run copilot:server and your app's dev server. See Getting started.

Capabilities So Far

Client -> Server -> Core -> (default executor | Model Runtime -> Provider) -> SSE -> Client

• @gixcopilot/protocol — transport-independent contracts (Message, Thread, Run, CopilotEvent, FinishReason), runtime validation, and (de)serialization.
• @gixcopilot/core — the framework-independent runtime: run lifecycle, event sequencing, cancellation, and a generic Executor boundary.
• @gixcopilot/provider — provider-neutral model contracts, a registry, and a ModelRuntime (retry, timeout, cancellation, usage, latency, normalized errors).
• @gixcopilot/provider-mock — a deterministic, non-network provider for tests/CI.
• @gixcopilot/provider-openai — a real OpenAI streaming provider (the only package depending on the openai SDK).
• @gixcopilot/server — a Fastify HTTP/SSE adapter, routing a request to either the default executor or a named model.
• @gixcopilot/client — a framework-independent streaming client (no React/Angular).
• @gixcopilot/react — provider, headless chat hooks, streaming state and actions, plus useCopilotContext/useCopilotState (Phase 4), useFrontendTool/useToolCalls (Phase 5), and useGenerativeComponent/useToolRenderer/useInvokeTool (Phase 6) hooks.
• @gixcopilot/ui — chat/popup/sidebar, safe Markdown, accessible controls and themes, with automatic generative-component/custom tool-result rendering (Phase 6).
• @gixcopilot/context — framework-independent application context registry/engine (scopes, priority, sensitivity, serialization, token budgeting/truncation, deduplication) and a shared typed state store, extended in Phase 6 with modelWritable/revision/ applyPatch; depends only on @gixcopilot/protocol.
• @gixcopilot/tools — framework-independent canonical tool architecture (ToolDefinition/defineTool, registry, resolver, execution runtime) shared by backend and frontend tools; depends only on @gixcopilot/protocol.
• @gixcopilot/generative-ui — framework-independent trusted component registry and the reserved-tool bridge that carries a model-selected component/state patch entirely over the canonical tool-calling pipeline; depends only on protocol/tools/context, never React.
• examples/react-basic / examples/react-custom-ui — styled and headless React examples.
• examples/react-context — application-aware chat example (Phase 4).
• examples/react-tools — backend/frontend tool calling example (Phase 5).
• examples/react-generative-ui — generative UI + AI-writable state example (Phase 6).
• Phases 7–10 — @gixcopilot/security, openapi, mcp, integrations, knowledge, rag, vectorstore-pgvector, memory, agents, workflows, jobs, checkpoint-postgres; see each phase's docs under docs/phases/.
• @gixcopilot/telemetry (Phase 11) — the TelemetryAdapter port (no-op, OpenTelemetry, in-memory recording), semantic conventions, safe redaction, sampling, metrics, cost estimation, and instrumentation wrappers for every runtime seam.
• @gixcopilot/devtools (Phase 11) — read-only, viewer-scoped inspectors over recorded diagnostics, safe debug bundles, and an opt-in authenticated /server transport; apps/devtools is the React DevTools UI.
• @gixcopilot/studio (post-Phase 12, experimental) — the development-only Developer Studio at /__gix: read-only project discovery, proposal-only generators (API/OpenAPI → tools, state → context, components → generative UI, auth → policies, agents, skills, knowledge), preview/diff, selective approval, and a deterministic apply engine with conflict detection, secret scanning and post-apply validation. Nothing changes in your repository until you approve it, and nothing is registered in production. See Developer Studio and ADR 0023.
• @gixcopilot/testing (Phase 11) — deterministic test models, tool mocks, security/RAG/ memory/approval fixtures, agent and workflow simulation, and side-effect-free replay.
• @gixcopilot/evals (Phase 11) — datasets, evaluators, reports, baseline comparison and CI gates in which security is a hard gate.
• Phase 12 SDKs — @gixcopilot/headless shares framework-neutral behavior between React and @gixcopilot/angular; @gixcopilot/node provides in-process and HTTP use; @gixcopilot/cli scaffolds projects, agents and tools.
• Phase 12 production — @gixcopilot/config, tenancy, persistence-postgres, redis, model-router, usage, and management power apps/api, apps/worker and the apps/platform control-plane UI. apps/docs serves the developer guides and production guides.
• examples/protocol-demo — the Phase 1 proof (no AI), CLI + integration test.
• examples/model-streaming — the Phase 2 proof (mock by default, optional real OpenAI), CLI + mandatory mock integration test + optional real-provider smoke test.

Package Structure

packages/
  protocol/             @gixcopilot/protocol
  core/                 @gixcopilot/core
  client/               @gixcopilot/client
  server/               @gixcopilot/server
  headless/             @gixcopilot/headless (shared chat behavior)
  react/                @gixcopilot/react (React hooks and provider)
  angular/              @gixcopilot/angular (Angular signals and components)
  vue/                  @gixcopilot/vue (Vue 3 plugin, composables and chat component)
  create/               @gixcopilot/create (npm create @gixcopilot installer)
  sdk/                  @gixcopilot/sdk (gix installer, Experimental/unreleased)
  node/                 @gixcopilot/node (Node integration)
  cli/                  @gixcopilot/cli (aicopilot command)
  ui/                   @gixcopilot/ui (optional components + CSS)
  context/              @gixcopilot/context (framework-independent context/state engine)
  tools/                @gixcopilot/tools (framework-independent canonical tool architecture)
  generative-ui/        @gixcopilot/generative-ui (framework-independent generative UI/state-patch bridge)
  security/ openapi/ mcp/ integrations/ knowledge/ rag/ memory/   (Phases 7-9)
  connectors/           @gixcopilot/connectors (any HTTP/GraphQL API as tools, manifests)
  vectorstores/pgvector/  agents/ workflows/ jobs/ checkpoint-postgres/   (Phases 9-10)
  telemetry/            @gixcopilot/telemetry (Phase 11)
  devtools/             @gixcopilot/devtools (+ /server) (Phase 11)
  studio/               @gixcopilot/studio (+ /server) Developer Studio, development only
  testing/              @gixcopilot/testing (Phase 11)
  evals/                @gixcopilot/evals (Phase 11)
  config/ tenancy/ persistence-postgres/ redis/ model-router/ usage/ management/ (Phase 12)
  providers/
    provider-core/      @gixcopilot/provider
    mock/               @gixcopilot/provider-mock
    openai/             @gixcopilot/provider-openai
examples/
  protocol-demo/        Phase 1 end-to-end CLI demo + integration test
  model-streaming/       Phase 2 end-to-end CLI demo + integration test + optional OpenAI smoke test
  react-basic/           Phase 3 interface lab + mock server + integration tests
  react-custom-ui/       Phase 3 headless-only example
  react-context/         Phase 4 application-context example + mock server + integration test
  react-tools/           Phase 5 backend/frontend tool example + mock server + integration tests
  react-generative-ui/   Phase 6 generative-UI/state-patch example + mock server + integration tests
  ...                   Phase 7-10 examples (react-enterprise, openapi, mcp, react-rag, agent-basic, multi-agent, workflow-*)
  devtools/             Phase 11 DevTools demo host + execution-generated trace
  evals/                Phase 11 evaluation example (deterministic + live OpenAI)
apps/
  devtools/             Phase 11 React DevTools UI
docs/
  architecture/         architecture overview
  adr/                  architecture decision records
  phases/phase-02/      Phase 2's own documentation set
  phases/phase-03/      Phase 3 API, validation, completion and handoff
  phases/phase-04/      Phase 4 API, validation, completion and handoff
  phases/phase-05/      Phase 5 API, validation, completion and handoff
  phases/phase-06/      Phase 6 API, validation, completion and handoff
  PROJECT_STATUS.md, DECISIONS.md, TECHNICAL_DEBT.md
.claude/
  skills/               the engineering skill system this project is built against

Dependency direction (enforced by @nx/enforce-module-boundaries, see eslint.config.js):

protocol  <-  core  <-  server
protocol  <-  client  <-  react  <-  ui
protocol  <-  context  <-  react
protocol  <-  tools  <-  react, server
protocol, tools, context  <-  generative-ui  <-  react
protocol  <-  core  <-  provider  <-  provider-mock, provider-openai (never each other)
provider  <-  server

protocol depends on nothing else in the workspace. core depends only on protocol — notably, not on provider; it's the other way around. See ADR 0006.

Development Commands

This is an Nx + pnpm monorepo.

pnpm install        # install workspace dependencies

pnpm lint           # nx run-many -t lint
pnpm typecheck      # nx run-many -t typecheck
pnpm test           # nx run-many -t test
pnpm build          # nx run-many -t build
pnpm validate       # all four, in one call

pnpm demo           # run the Phase 1 end-to-end CLI demo
pnpm demo:react      # after build: React examples on 5173/5174, mock server on 4318
pnpm test:e2e        # builds examples and runs credential-free Chromium tests

Each command also works scoped to a single project, e.g. pnpm --filter @gixcopilot/core test, or via Nx directly: npx nx run core:test, npx nx run-many -t test --projects=core,server.

Run the Phase 2 model-streaming demo with pnpm --filter @gixcopilot/model-streaming-demo run demo (mock provider by default; set OPENAI_API_KEY and MODEL_PROVIDER=openai for real streaming — see examples/model-streaming/README.md).

For React, run pnpm build && pnpm demo:react, then open http://127.0.0.1:5173. The standalone headless example is on port 5174. Both use the existing runtime through HTTP/SSE. For browser tests, first run pnpm exec playwright install chromium.

import { CopilotProvider } from '@gixcopilot/react';
import { CopilotPopup } from '@gixcopilot/ui';
import '@gixcopilot/ui/styles.css';

export function App() {
  return (
    <CopilotProvider runtimeUrl="/api/copilot">
      <CopilotPopup suggestions={['Explain SSE']} />
    </CopilotProvider>
  );
}

The runtime URL is a base URL; requests go to /api/copilot/runs. See the React API for custom clients and headless hooks. Install from npm, for example npm install @gixcopilot/react react or npm install @gixcopilot/node @gixcopilot/provider-openai; see Releasing.

Phase 12 developer and production guides

• Start with Getting started and the examples.
• SDK guides: React, Vue, Angular, and Node.
• Application features: tools, generative UI, security, connect any API, OpenAPI, MCP, Next.js, RAG, memory, agents, and workflows.
• Operations: CLI, platform, DevTools, testing, evaluations, production, and deployment.
• API reference, versioning, and release process. Contributors should read AGENTS.md.
• The website and documentation portal (apps/docs): how to run, write and deploy it.

Capability maturity

All 43 packages are published to npm together at one version (0.2.2, pre-1.0). Each package README states its stability level; the policy and full list are in Versioning.

The sample apps (apps/platform, apps/api, apps/worker) are reference deployments, not published packages. Multi-instance API deployments need session affinity; see Scaling.

Testing

Vitest for unit/integration tests. examples/protocol-demo/src/integration.spec.ts and examples/model-streaming/src/integration.spec.ts are the full end-to-end proofs (client → real HTTP → real server → core → [model runtime →] SSE → client, including cancellation), run against a real, in-process Fastify server — no mocks of our own code, no external AI service required for either. examples/model-streaming/src/openai-smoke.spec.ts is an optional real-network test against the actual OpenAI API, skipped (not failed) unless OPENAI_API_KEY is set — never part of the deterministic CI requirement.

Architecture

See docs/architecture/overview.md for package responsibilities and the full request/response flow, and docs/adr/ for the specific decisions made and why. Each package also has its own README describing its public API and, importantly, its non-responsibilities — what it deliberately does not do, to keep architecture drift from creeping in as later phases are built.

Engineering Standards

AGENTS.md is the entry point for any coding agent working in this repo, and CONSTITUTION.md is the non-negotiable law it defers to — framework independence, phase discipline, the trust boundary around model output, verified-completion requirements, and dependency discipline. Everything below that is an explicit skill system in .claude/skills/, covering architecture, TypeScript standards, security, testing, and more — see .claude/skills/README.md. Development proceeds through 12 fixed phases with an explicit phase-gate: work never silently continues from one phase to the next.

License

MIT