openvibers/openvibe.sdk Commits

Add model plans to the existing Codes SDK client (v0.149.0) (#224)

OP OpenVibers committed 2 days ago · ac6eb7faa2 · 11 files, +84 −13

* Add model plans to existing Codes SDK client

* Match model plan types and Space handoff behavior

* Update SDK version in core and browser bundle

Changes

ddiff --git a/CHANGELOG.md b/CHANGELOG.md
iindex 498a20c..a7edc18 100644
---- a/CHANGELOG.md
++++ b/CHANGELOG.md
@@@ -1,5 +1,9 @@
  # Changelog
  
++## 0.149.0 — 2026-11-11
++
++- Extend the existing `codes` client with `modelPlans.get/put/presets()` and `tasks.create({ plan | preset })`, typed for `codes.model-plan@1` on Contracts 0.406.0.
++
  ## 0.148.0 — 2026-11-11
  
  - #208: add `openvibe-sdk/composer`, the shared composer's client: `attachments.upload(file, { onProgress, signal })` (multipart through `XMLHttpRequest`, real browser progress), `attachments.remove(id)`, `composer.prefs.get()/put(prefs, rev)` and `mentions.search(q, kinds)`, typed by `composer.attachment@1`, `composer.prefs@1` and `composer.mention@1`.
ddiff --git a/README.md b/README.md
iindex a9feb2b..a6e74a7 100644
---- a/README.md
++++ b/README.md
@@@ -8,12 +8,12 @@
  **Install and test:** `npm ci && npm test` (Node 20 or newer)
  
  ```bash
--npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.148.0
++npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.149.0
  ```
  
  > Supported browser and server clients for the OpenVibe platform.
  
--**Status:** alpha, v0.148.0 (the five 1.0 core entries — `core`, `auth`, `events`, `db` and `media` — are frozen: their exported names change only with a major release; roadmap Wave 2; developer apps from Wave 20; Media objects v2 from Wave 4; the Tools platform API; Search, Chat, AI, Vision and consent clients; sign-in with recovery and a client health check). Every release is tagged (see [CHANGELOG.md](CHANGELOG.md)). Tested against local stub servers and the built-in mock platform only, never against the live platform. Services pin release tags; each repository's `STATUS.json` names the one it uses.
++**Status:** alpha, v0.149.0 (the five 1.0 core entries — `core`, `auth`, `events`, `db` and `media` — are frozen: their exported names change only with a major release; roadmap Wave 2; developer apps from Wave 20; Media objects v2 from Wave 4; the Tools platform API; Search, Chat, AI, Vision and consent clients; sign-in with recovery and a client health check). Every release is tagged (see [CHANGELOG.md](CHANGELOG.md)). Tested against local stub servers and the built-in mock platform only, never against the live platform. Services pin release tags; each repository's `STATUS.json` names the one it uses.
  **Plan:** OpenVibe End-to-End Realignment & Implementation Plan, revision 3 (20 Sep 2026), §3.2; roadmap §30.  
  **License:** MIT ([LICENSE](LICENSE)). This package is a library that apps outside the network embed, so it uses MIT. The OpenVibe services themselves stay AGPL-3.0.
  
@@@ -22,7 +22,7 @@ npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags
  After v0.97.1 is tagged:
  
  ```bash
--npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.148.0
++npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.149.0
  ```
  
  It has no runtime dependencies. It needs Node ≥ 20, or any browser with `fetch`, Web Crypto and `TextDecoder`. There is no build step. The package is CommonJS with ESM entry points (`import` works). Each subpath has its own `.d.ts`. For a page with no bundler, `browser/openvibe-sdk.mjs` is one self-contained ES module of the browser-safe subpaths (see [Browser without a bundler](#browser-without-a-bundler)). It does not depend on `openvibe-contracts` at runtime: it copies the contract types it uses (from the temporary Contracts sharing branch, a devDependency the tests check them against).
ddiff --git a/STATUS.json b/STATUS.json
iindex 4d8a80c..4974e4a 100644
---- a/STATUS.json
++++ b/STATUS.json
@@@ -3,7 +3,7 @@
    "stage": "alpha",
    "code": true,
    "wave": "W2",
--  "version": "0.148.0",
++  "version": "0.149.0",
    "plan": "OpenVibe End-to-End Realignment & Implementation Plan, revision 3 (20 Sep 2026), §3.2; roadmap §30",
    "deployed": false,
    "deployment": "none: a package released as git tags; services and apps pin a tag",
ddiff --git a/browser/openvibe-sdk.mjs b/browser/openvibe-sdk.mjs
iindex 15c8895..46dd6d8 100644
---- a/browser/openvibe-sdk.mjs
++++ b/browser/openvibe-sdk.mjs
@@@ -1,4 +1,4 @@
--// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.148.0, MIT). Do not edit.
++// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.149.0, MIT). Do not edit.
  // One self-contained ES module: core at the top level plus the browser-safe subpaths as namespaces
  // (auth, locker, registry, trust, levels, modules, realtime, media, composer, cam, mediaUpload, ui, community, homeFeed, feed, bot, search, bench, meme, vision, themes, design, redact, chat, ai, credentials, jobs, agents, tools, projects, geo, history, userCard, player, agentSheet). No server-only code: no service tokens, JWT verification, events, identity.
  /* eslint-disable */
@@@ -64,7 +64,7 @@ const { paginate, offsetPager } = __load(7);
  const semver = __load(6);
  
  /** The package version (test/version.test.js keeps it equal to package.json). */
--const SDK_VERSION = '0.148.0';
++const SDK_VERSION = '0.149.0';
  
  module.exports = {
      createClient,
ddiff --git a/docs/codes.md b/docs/codes.md
nnew file mode 100644
iindex 0000000..b2d266f
---- /dev/null
++++ b/docs/codes.md
@@@ -0,0 +1,17 @@
++# Codes model plans
++
++`openvibe-sdk/codes` uses a person's Network token for coding tasks and model plans.
++
++```js
++const { createClient } = require('openvibe-sdk/core');
++const { createCodesClient } = require('openvibe-sdk/codes');
++const codes = createCodesClient(createClient({ tokenProvider }));
++
++const { presets } = await codes.modelPlans.presets();
++const saved = await codes.modelPlans.put(presets.Balanced); // account default
++const project = await codes.modelPlans.get({ project: 'prj_...' });
++await codes.tasks.create({ text: 'Fix the parser', mode: 'repo', repo: 'owner/repo', preset: 'Deep' });
++await codes.tasks.create({ text: 'Fix the parser', mode: 'repo', repo: 'owner/repo', plan: saved.resolved });
++```
++
++Pass `{ project }` to `modelPlans.put(plan, { project })` to save a project default. A task accepts either `plan` or `preset`. The service checks models against AI's registry and returns resolved choices and fallback reasons when a plan is saved.
ddiff --git a/package-lock.json b/package-lock.json
iindex a07063c..4c3560a 100644
---- a/package-lock.json
++++ b/package-lock.json
@@@ -1,12 +1,12 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.148.0",
++  "version": "0.149.0",
    "lockfileVersion": 3,
    "requires": true,
    "packages": {
      "": {
        "name": "openvibe-sdk",
--      "version": "0.148.0",
++      "version": "0.149.0",
        "license": "MIT",
        "bin": {
          "openvibe-download": "bin/openvibe-download.js"
ddiff --git a/package.json b/package.json
iindex edcf39b..04006b4 100644
---- a/package.json
++++ b/package.json
@@@ -1,6 +1,6 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.148.0",
++  "version": "0.149.0",
    "description": "Supported browser and server clients for the OpenVibe platform: auth (incl. developer apps), registry discovery, identity, user modules, events, realtime, media, community, Bot robots, search, chat, AI runs, Tools (registry, run API and jobs), VIP memberships and developer projects, the async PostgreSQL data layer (db) and the Valkey cache, limits store, queue and pub/sub, with deadlines, safe retries, problem errors and trace propagation.",
    "main": "index.js",
    "types": "types/index.d.ts",
ddiff --git a/src/codes.js b/src/codes.js
iindex bd9ef8b..e273d33 100644
---- a/src/codes.js
++++ b/src/codes.js
@@@ -15,6 +15,7 @@ const enc = encodeURIComponent;
  
  const TASK = /^tsk_[0-9A-HJKMNP-TV-Z]{26}$/;
  const MODES = ['create', 'openvibe', 'repo'];
++const PRESETS = ['Fast', 'Balanced', 'Deep', 'Council'];
  
  function createCodesClient(client, { baseUrl } = {}) {
      if (!client || typeof client.json !== 'function' || typeof client.request !== 'function') throw new TypeError('createCodesClient: pass an openvibe-sdk/core client');
@@@ -35,21 +36,38 @@ function createCodesClient(client, { baseUrl } = {}) {
                  return call({ path: '/api/v1/me/tasks', query: { limit: n }, signal });
              },
              /** Start one the Dock's way: the words, where it starts, and what it carries. → { id, url }. */
--            create: ({ text, mode, repo, attachments } = {}, { signal } = {}) => {
++            create: ({ text, mode, repo, attachments, plan, preset } = {}, { signal } = {}) => {
                  if (typeof text !== 'string' || !text.trim()) throw new TypeError('codes.tasks.create: text is the instruction in plain words');
                  if (!MODES.includes(mode)) throw new TypeError('codes.tasks.create: mode is create, openvibe or repo');
                  if (repo != null && (typeof repo !== 'string' || !repo.trim())) throw new TypeError('codes.tasks.create: repo is a repository address');
                  if (attachments != null && (!Array.isArray(attachments) || attachments.some((a) => typeof a !== 'string'))) {
                      throw new TypeError('codes.tasks.create: attachments are composer attachment ids');
                  }
++                if (plan != null && (typeof plan !== 'object' || Array.isArray(plan))) throw new TypeError('codes.tasks.create: plan is a model plan object');
++                if (preset != null && !PRESETS.includes(preset)) throw new TypeError('codes.tasks.create: preset is Fast, Balanced, Deep or Council');
++                if (plan != null && preset != null) throw new TypeError('codes.tasks.create: choose plan or preset');
++                if (mode === 'create' && (plan != null || preset != null)) throw new TypeError('codes.tasks.create: model plans apply to coding tasks, not Space handoffs');
                  return once({
                      method: 'POST', path: '/api/v1/tasks',
--                    json: { text, mode, ...(repo ? { repo } : {}), ...(attachments ? { attachments } : {}) }, signal,
++                    json: { text, mode, ...(repo ? { repo } : {}), ...(attachments ? { attachments } : {}),
++                        ...(plan ? { plan } : {}), ...(preset ? { preset } : {}) }, signal,
                  });
              },
              /** Stop the running attempt; nothing carries it on. → { ok: true }. */
              stop: (taskId, { signal } = {}) => once({ method: 'POST', path: `/api/v1/tasks/${id(taskId)}/stop`, signal }),
          },
++        modelPlans: {
++            /** The account default and optional project's effective plan. */
++            get: ({ project, signal } = {}) => call({ path: '/api/v1/model-plans', ...(project ? { query: { project } } : {}), signal }),
++            /** Save an account or project plan; the service validates models and returns its resolved choices. */
++            put: (plan, { project, signal } = {}) => {
++                if (!plan || typeof plan !== 'object' || Array.isArray(plan)) throw new TypeError('codes.modelPlans.put: plan is a model plan object');
++                if (project != null && (typeof project !== 'string' || !project.trim())) throw new TypeError('codes.modelPlans.put: project is a project id');
++                return once({ method: 'PUT', path: '/api/v1/model-plans', ...(project ? { query: { project } } : {}), json: { plan }, signal });
++            },
++            /** Copyable Fast, Balanced, Deep and Council plans. */
++            presets: ({ signal } = {}) => call({ path: '/api/v1/model-plans/presets', signal }),
++        },
      };
  }
  
ddiff --git a/src/core/index.js b/src/core/index.js
iindex 0c729d7..8fa3bdd 100644
---- a/src/core/index.js
++++ b/src/core/index.js
@@@ -8,7 +8,7 @@ const { paginate, offsetPager } = require('./paginate');
  const semver = require('./semver');
  
  /** The package version (test/version.test.js keeps it equal to package.json). */
--const SDK_VERSION = '0.148.0';
++const SDK_VERSION = '0.149.0';
  
  module.exports = {
      createClient,
ddiff --git a/test/codes.test.js b/test/codes.test.js
iindex 8214401..98765d3 100644
---- a/test/codes.test.js
++++ b/test/codes.test.js
@@@ -21,6 +21,9 @@ const summary = (over = {}) => ({
              seen.push({ method: req.method, url: req.url, auth: req.headers.authorization || null, body });
              const json = (status, obj) => { res.writeHead(status, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(obj)); };
              if (req.url === '/api/v1/me/tasks?limit=8' && req.method === 'GET') return json(200, { tasks: [summary()] });
++            if (req.url === '/api/v1/model-plans/presets' && req.method === 'GET') return json(200, { presets: { Fast: { mode: 'single' } } });
++            if (req.url.startsWith('/api/v1/model-plans') && req.method === 'GET') return json(200, { account: { mode: 'pair' }, effective: { mode: 'pair' } });
++            if (req.url.startsWith('/api/v1/model-plans') && req.method === 'PUT') return json(200, { resolved: JSON.parse(body).plan });
              if (req.url === '/api/v1/tasks' && req.method === 'POST') {
                  const b = JSON.parse(body);
                  if (b.mode === 'create') return json(200, { id: null, url: 'https://openvibe.space/auth/login?next=%2Fspaces%2Fnew' });
@@@ -42,6 +45,16 @@ const summary = (over = {}) => ({
          assert.strictEqual(space.id, null);
          assert.ok(space.url.startsWith('https://openvibe.space'));
          assert.deepStrictEqual(await codes.tasks.stop(TASK), { ok: true });
++        const plan = { mode: 'single', roles: [{ role: 'builder', model: 'auto', effort: 'low' }], checks: { tests: true, lint: false, reviewer: false } };
++        assert.equal((await codes.modelPlans.get()).effective.mode, 'pair');
++        assert.equal((await codes.modelPlans.get({ project: 'prj_example' })).account.mode, 'pair');
++        assert.deepStrictEqual(await codes.modelPlans.put(plan, { project: 'prj_example' }), { resolved: plan });
++        assert.equal((await codes.modelPlans.presets()).presets.Fast.mode, 'single');
++        await codes.tasks.create({ text: 'Use a preset', mode: 'repo', preset: 'Deep' });
++        await codes.tasks.create({ text: 'Use a plan', mode: 'repo', plan });
++        assert.equal(JSON.parse(seen.find((s) => s.url === '/api/v1/tasks' && JSON.parse(s.body).preset === 'Deep').body).preset, 'Deep');
++        assert.deepStrictEqual(JSON.parse(seen.find((s) => s.url === '/api/v1/tasks' && JSON.parse(s.body).plan).body).plan, plan);
++        assert.deepStrictEqual(JSON.parse(seen.find((s) => s.url === '/api/v1/model-plans?project=prj_example' && s.method === 'PUT').body), { plan });
  
          const posted = JSON.parse(seen.find((s) => s.url === '/api/v1/tasks' && JSON.parse(s.body).mode === 'repo').body);
          assert.deepStrictEqual(posted, { text: 'Add a test.', mode: 'repo', repo: 'octocat/Hello-World' });
@@@ -52,6 +65,10 @@ const summary = (over = {}) => ({
          assert.throws(() => codes.tasks.create({ text: 'Hi', mode: 'repo', repo: '  ' }), /repo is a repository/);
          assert.throws(() => codes.tasks.create({ text: 'Hi', mode: 'repo', attachments: [42] }), /attachment ids/);
          assert.throws(() => codes.tasks.stop('nope'), /tsk_/);
++        assert.throws(() => codes.tasks.create({ text: 'Hi', mode: 'repo', plan, preset: 'Fast' }), /choose plan or preset/);
++        assert.throws(() => codes.tasks.create({ text: 'Hi', mode: 'repo', preset: 'Unknown' }), /preset is Fast/);
++        assert.throws(() => codes.tasks.create({ text: 'Hi', mode: 'create', preset: 'Fast' }), /coding tasks/);
++        assert.throws(() => codes.modelPlans.put(null), /plan is a model plan/);
          console.log('  ok  codes tasks: list, create (repo and create), stop, and every validation');
      } finally {
          await new Promise((r) => server.close(r));
ddiff --git a/types/codes.d.ts b/types/codes.d.ts
iindex dbbf2f8..e492883 100644
---- a/types/codes.d.ts
++++ b/types/codes.d.ts
@@@ -3,12 +3,22 @@ type Opts = { signal?: AbortSignal };
  type CodesJson = Record<string, any>;
  export type CodesTaskMode = 'create' | 'openvibe' | 'repo';
  export type CodesTaskStatus = 'queued' | 'running' | 'needs-you' | 'done' | 'failed' | 'stopped';
++export type CodesModelPreset = 'Fast' | 'Balanced' | 'Deep' | 'Council';
++export type CodesModelEffort = 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
++export interface CodesModelPlan {
++    mode: 'single' | 'pair' | 'council' | 'escalate';
++    roles: Array<{ role: 'planner' | 'builder' | 'reviewer' | 'verifier'; model: string; effort: CodesModelEffort;
++        samples?: number; budget?: { tokens?: number; minutes?: number; dollars?: number } }>;
++    ladder?: string[];
++    checks: { tests?: boolean; lint?: boolean; reviewer?: boolean };
++}
  export interface CodesTaskSummary {
      id: string; title: string; status: CodesTaskStatus; mode: CodesTaskMode; repo: string;
      started_at: string; updated_at: string; steps: number; url: string; preview_url: string | null; pr_url: string | null;
  }
  export interface CodesTaskCreate {
      text: string; mode: CodesTaskMode; repo?: string; attachments?: string[];
++    plan?: CodesModelPlan; preset?: CodesModelPreset;
  }
  export interface CodesClient {
      tasks: {
@@@ -16,5 +26,10 @@ export interface CodesClient {
          create(req: CodesTaskCreate, opts?: Opts): Promise<{ id: string | null; url: string }>;
          stop(id: string, opts?: Opts): Promise<{ ok: true }>;
      };
++    modelPlans: {
++        get(opts?: Opts & { project?: string }): Promise<{ account: CodesModelPlan; project: CodesModelPlan | null; effective: CodesModelPlan; source: 'account' | 'project' }>;
++        put(plan: CodesModelPlan, opts?: Opts & { project?: string }): Promise<{ plan: CodesModelPlan; resolved: CodesModelPlan; fallbacks: unknown[]; prices: unknown[] }>;
++        presets(opts?: Opts): Promise<{ presets: Record<CodesModelPreset, CodesModelPlan> }>;
++    };
  }
--export declare function createCodesClient(client: CodesJson, opts?: { baseUrl?: string }): { tasks: CodesClient['tasks'] };
++export declare function createCodesClient(client: CodesJson, opts?: { baseUrl?: string }): CodesClient;