@orkestral-ai/forge-sync

Behavioral-signal transport for Orkestral Forge — ships how a developer works with code, never the code itself, so the Forge model keeps getting better.

🇺🇸 English

What it is

@orkestral-ai/forge-sync is the thin client library that the Orkestral desktop app uses to send behavioral signals to the Orkestral cloud.

A behavioral signal is small, code-free metadata about how a developer handles their work — for example: whether they accepted or rejected a Forge edit, whether the local Forge model or a premium model produced the preferred result, or what kind of correction was applied. The user's source code never leaves their machine — only these decision signals do.

These signals feed the central distillation that makes Forge — a code model that runs 100% on the user's machine, at $0 per task — smarter every day.

Where it fits

premium model PLANS → Forge EXECUTES → review VERIFIES
        │  (code-free signal: verdict · winner · correction type)
        ▼
   forge-sync.capture() → flush() → Orkestral cloud (Supabase Edge Function)
        ▼
   daily distillation (GPU) → new Forge version → synced back to every app

This package is only the transport. It has no endpoints or keys baked in — the app passes them at runtime (endpoint, getToken). The proprietary logic lives in the Orkestral app and the cloud trainer; this is just the pipe.

The privacy barrier

The model learns how you deal with code — never your code. As defense in depth, capture() drops any string field longer than 2,000 characters (a likely sign of file content leaking in by accident).

Install

npm install @orkestral-ai/forge-sync

Usage

import { createForgeSync } from '@orkestral-ai/forge-sync';

const sync = createForgeSync({
  endpoint: 'https://<project>.supabase.co/functions/v1/forge-signals',
  getToken: () => orkestralCloudJwt, // the signed-in user's JWT, or null
  appVersion: '0.1.1',
});

// At verification points — code-free metadata only:
sync.capture({ type: 'review_verdict', verdict: 'approved', executor: 'forge' });
sync.capture({ type: 'forge_vs_premium', winner: 'forge' });

await sync.flush(); // best-effort; on failure, signals stay queued for retry

API

| Member | Description | |---|---| | createForgeSync(options) | Creates a sync client. | | options.endpoint | Ingest endpoint (Supabase Edge Function URL). | | options.getToken | () => string \| null \| Promise<…> — the user's auth token. | | options.appVersion? | Attached to each batch (cohort telemetry). | | options.maxBatch? | Signals per request (default 50). | | options.fetchImpl? | Custom fetch (tests). | | sync.capture(signal) | Queue a code-free signal. Non-blocking. | | sync.flush() | Promise<{ sent, skipped, reason? }> — send pending; keeps them on failure. | | sync.pending() | Number of queued signals. |

A ForgeSignal is { type: string, ...codeFreeMetadata }.

Build

npm install
npm run build   # tsup → minified ESM + CJS + .d.ts in dist/

License

Proprietary — UNLICENSED. © Orkestral. The source lives in a private repository; only the minified build is published to npm.

🇧🇷 Português

O que é

@orkestral-ai/forge-sync é a biblioteca cliente enxuta que o app desktop do Orkestral usa pra enviar sinais de comportamento pra nuvem do Orkestral.

Um sinal de comportamento é um metadado pequeno e sem código sobre como o dev lida com o trabalho — por exemplo: se ele aceitou ou rejeitou uma edição do Forge, se o Forge local ou um modelo premium gerou o resultado preferido, ou que tipo de correção foi aplicada. O código-fonte do usuário NUNCA sai da máquina — só esses sinais de decisão saem.

Esses sinais alimentam a destilação central que deixa o Forge — um modelo de código que roda 100% na máquina do usuário, com custo $0 por tarefa — melhor a cada dia.

Onde se encaixa

modelo premium PLANEJA → Forge EXECUTA → review VERIFICA
        │  (sinal sem código: veredito · vencedor · tipo de correção)
        ▼
   forge-sync.capture() → flush() → nuvem Orkestral (Supabase Edge Function)
        ▼
   destilação diária (GPU) → versão nova do Forge → sincroniza de volta em todo app

Este pacote é só o transporte. Não tem endpoint nem chave embutidos — o app passa em runtime (endpoint, getToken). A lógica proprietária vive no app Orkestral e no treinador da nuvem; aqui é só o cano.

A barreira de privacidade

O modelo aprende como você lida com o código — nunca o seu código. Como defesa em profundidade, o capture() descarta qualquer campo string acima de 2.000 caracteres (provável sinal de conteúdo de arquivo vazando sem querer).

Instalar

npm install @orkestral-ai/forge-sync

Uso

import { createForgeSync } from '@orkestral-ai/forge-sync';

const sync = createForgeSync({
  endpoint: 'https://<projeto>.supabase.co/functions/v1/forge-signals',
  getToken: () => orkestralCloudJwt, // o JWT do usuário logado, ou null
  appVersion: '0.1.1',
});

// Nos pontos de verificação — só metadado sem código:
sync.capture({ type: 'review_verdict', verdict: 'approved', executor: 'forge' });
sync.capture({ type: 'forge_vs_premium', winner: 'forge' });

await sync.flush(); // best-effort; em falha, os sinais ficam na fila pra retry

Build

npm install
npm run build   # tsup → ESM + CJS + .d.ts minificados em dist/

Licença

Proprietária — UNLICENSED. © Orkestral. O source vive num repositório privado; só o build minificado é publicado no npm.