openvibers/openvibe.sdk Commits

openvibe-sdk/actor: agent contacts and approval levels (#131)

OP OpenVibers committed 6 days ago · dad6f22e19 · 11 files, +131 −18

{
	"message": "API rate limit exceeded for user ID 279216588. If you reach out to GitHub Support for help, please include the request ID B018:1B377B:144E084:1D32C7F:6AEF1DBF and timestamp 2026-11-07 12:46:55 UTC. For more on scraping GitHub and how it may affect your rights, please review our Terms of Service (https:\/\/docs.github.com\/en\/site-policy\/github-terms\/github-terms-of-service)",
	"documentation_url": "https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api#rate-limiting",
	"status": "403"
}

Changes

ddiff --git a/CHANGELOG.md b/CHANGELOG.md
iindex 66a02a9..f8a4520 100644
---- a/CHANGELOG.md
++++ b/CHANGELOG.md
@@@ -1,5 +1,12 @@
  # Changelog
  
++## 0.96.0 (2026-11-07)
++
++- `openvibe-sdk/actor` gains `contacts`: `list()`, `presets()`, `get()`, `create()` (optionally from a preset),
++  `update()`, `remove()` and `setLevel()`, for a person's agents as contacts and their approval levels (plan §12
++  A-1). `contacts.list()` is `GET /api/v1/agents` with the person's own token, which now answers their contacts
++  (Vibe first), so `agents.list()` and the new `agents.catalog()` call the explicit public catalog
++  `GET /api/v1/agent-systems` and keep their old meaning. `tasks.create` types `agent_id` and `level`.
  ## 0.95.0 (2026-11-07)
  
  - Add `openvibe-sdk/cam`: `defineOvCamera({ src })` injects OpenVibe.Cam's framework-free `<ov-camera>` element
ddiff --git a/README.md b/README.md
iindex 588c074..feebcdd 100644
---- a/README.md
++++ b/README.md
@@@ -2,16 +2,16 @@
  
  > Supported browser and server clients for the OpenVibe platform.
  
--**Status:** alpha, v0.95.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.96.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.
  
  **If a capability is not in the SDK, it is not public.** Apps call services through `openvibe-sdk` and never build internal routes themselves. A route with no SDK wrapper is internal, even when you can reach it, and it can change without notice. To make a capability public, first define it in OpenVibe.Contracts, then wrap it here.
  
--After v0.95.0 is tagged:
++After v0.96.0 is tagged:
  
  ```bash
--npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.95.0
++npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.96.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 7c60bde..543c338 100644
---- a/STATUS.json
++++ b/STATUS.json
@@@ -3,7 +3,7 @@
    "stage": "alpha",
    "code": true,
    "wave": "W2",
--  "version": "0.95.0",
++  "version": "0.96.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 f3e9c54..be9e07c 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.95.0, MIT). Do not edit.
++// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.96.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, modules, realtime, media, community, bot, search, bench, meme, vision, themes, redact, chat, ai, jobs, tools, projects, geo). No server-only code: no service tokens, JWT verification, events, identity.
  /* eslint-disable */
@@@ -48,7 +48,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.95.0';
++const SDK_VERSION = '0.96.0';
  
  module.exports = {
      createClient,
ddiff --git a/package-lock.json b/package-lock.json
iindex d94a192..a48e967 100644
---- a/package-lock.json
++++ b/package-lock.json
@@@ -1,12 +1,12 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.95.0",
++  "version": "0.96.0",
    "lockfileVersion": 3,
    "requires": true,
    "packages": {
      "": {
        "name": "openvibe-sdk",
--      "version": "0.95.0",
++      "version": "0.96.0",
        "license": "MIT",
        "bin": {
          "openvibe-download": "bin/openvibe-download.js"
ddiff --git a/package.json b/package.json
iindex 70e7235..dae949a 100644
---- a/package.json
++++ b/package.json
@@@ -1,6 +1,6 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.95.0",
++  "version": "0.96.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/actor.js b/src/actor.js
iindex e56533c..678c0f4 100644
---- a/src/actor.js
++++ b/src/actor.js
@@@ -5,18 +5,23 @@
   * https://openvibe.actor/api/v1; tokens for audience openvibe.actor.
   *
   *   const actor = createActorClient(createClient({ tokenProvider }));
-- *   const { agents } = await actor.agents.list();                                          // the agent systems (public)
++ *   const { agents } = await actor.agents.catalog();                                        // the agent systems (public)
   *   const plan = await actor.route({ task: 'Summarize this repo', mode: 'cheapest' });     // dry run: which agent, what cost
   *   const task = await actor.tasks.create({ task: 'Summarize …', idempotency_key: 'job-42' });
   *   for await (const e of actor.tasks.events(task.id)) console.log(e.event, e.data);      // until the task ends
++ *   const contacts = await actor.contacts.list();                                           // your agents, Vibe first
++ *   await actor.contacts.setLevel(contacts.agents[0].id, 'auto-edits');
   *   const mine = await actor.me.agents.create({ name: 'Morning brief', instructions: '…' });
   *   await actor.me.agents.run(mine.id, { input: 'today' });
   *   await actor.me.agents.memory.add(mine.id, 'I live in Portland');
   *
-- * A task is its requester's own (actor.task-create-request@1: task, mode, budget, agent, idempotency_key, webhooks).
-- * When it names webhooks, the answer that creates it carries webhook_secret, once. tasks.create is retried only when
-- * the body has an idempotency_key (Actor answers a repeat with the first task); the other writes are never retried on
-- * their own. A person's agents need the person's own token (an app's or another person's is 404).
++ * A task is its requester's own (actor.task-create-request@1: task, mode, budget, agent, agent_id, level,
++ * idempotency_key, webhooks). agent_id names one of the person's contacts (absent: Vibe) and level is the thread's own
++ * level; the effective level is the higher of the agent's and the person's own thread line, with an always-ask floor
++ * for money, passwords, deletions and sending to a new recipient. When a task names webhooks, the answer that creates
++ * it carries webhook_secret, once. tasks.create is retried only when the body has an idempotency_key (Actor answers a
++ * repeat with the first task); the other writes are never retried on their own. A person's agents and contacts need
++ * the person's own token (an app's or another person's is 404).
   * Errors are OpenVibeError: actor.task.invalid, actor.budget.over_tier, actor.idempotency.conflict (409),
   * actor.webhook.refused, actor.agent.invalid, actor.agent.limit (429), actor.agent.not_found, actor.task.not_found, …
   */
@@@ -39,6 +44,7 @@ function createActorClient(client, { baseUrl } = {}) {
          return enc(String(v));
      };
      const agentPath = (agent, rest = '') => `/api/v1/me/agents/${id('agent', agent)}${rest}`;
++    const contactPath = (agent, rest = '') => `/api/v1/agents/${id('agent', agent)}${rest}`;
  
      /**
       * A task's events as they happen (SSE: { id, event, data }), the backlog after lastEventId first; it ends when
@@@ -60,7 +66,24 @@ function createActorClient(client, { baseUrl } = {}) {
      return {
          agents: {
              /** The agent systems a task can go to, with what they are good at and cost (public). */
++            catalog: ({ signal } = {}) => call({ path: '/api/v1/agent-systems', signal }),
++            /** Alias of catalog: the public catalog, never the caller's own contacts. */
++            list: ({ signal } = {}) => call({ path: '/api/v1/agent-systems', signal }),
++        },
++        /** The person's own agents as contacts (actor.agent@1) and their approval levels (plan §12 A-1). */
++        contacts: {
++            /** Their contacts, Vibe first; Vibe is created on this first read. */
              list: ({ signal } = {}) => call({ path: '/api/v1/agents', signal }),
++            /** The four presets the UI can show (Researcher, Inbox, Studio editor, Party host). */
++            presets: ({ signal } = {}) => call({ path: '/api/v1/agents/presets', signal }),
++            get: (agent, { signal } = {}) => call({ path: contactPath(agent), signal }),
++            /** Create one, optionally from a preset: { preset, name?, face?, voice?, model?, computer?, apps?, memory?, level? }. */
++            create: (agent, { signal } = {}) => once({ method: 'POST', path: '/api/v1/agents', json: agent, signal }),
++            update: (agent, patch, { signal } = {}) => call({ method: 'PATCH', path: contactPath(agent), json: patch, idempotent: true, signal }),
++            /** Vibe is not deletable (Actor answers 409 actor.agent.vibe). */
++            remove: (agent, { signal } = {}) => call({ method: 'DELETE', path: contactPath(agent), signal }),
++            /** actor.level-change@1: { level } (ask | auto-edits | approve-for-me | full). */
++            setLevel: (agent, level, extra = {}, { signal } = {}) => call({ method: 'PUT', path: contactPath(agent, '/level'), json: { level, ...extra }, idempotent: true, signal }),
          },
          /** A dry run (public): the task's class and the agent and budget Actor would pick, nothing started. */
          route: ({ task, mode, agent } = {}, { signal } = {}) => call({ method: 'POST', path: '/api/v1/route', json: { task, mode, agent }, idempotent: true, signal }),
ddiff --git a/src/core/index.js b/src/core/index.js
iindex 035ba45..ddbf4dc 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.95.0';
++const SDK_VERSION = '0.96.0';
  
  module.exports = {
      createClient,
ddiff --git a/test/actor.test.js b/test/actor.test.js
nnew file mode 100644
iindex 0000000..b82c2d1
---- /dev/null
++++ b/test/actor.test.js
@@@ -0,0 +1,63 @@
++'use strict';
++// openvibe-sdk/actor: the agent contacts and approval levels (plan §12 A-1) through a real core client against a local
++// stub, plus the public catalog's explicit /api/v1/agent-systems path (a person's /api/v1/agents is their contacts).
++const assert = require('assert');
++const http = require('http');
++const { createClient } = require('../src/core');
++const { createActorClient } = require('../src/actor');
++
++const AGENT = 'agt_01M4C49CW34NGX7TR2TNRVFWNW';
++const agent = (over = {}) => ({
++    id: AGENT, owner: 'user:usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1', name: 'Vibe', face: 'preset:vibe', voice: null,
++    model: { engine: 'runtime', model: 'smart' }, computer: null, apps: [], memory: null, level: 'ask',
++    created_at: '2026-11-07T09:30:00.000Z', ...over,
++});
++
++(async () => {
++    const seen = [];
++    const server = http.createServer((req, res) => {
++        let body = '';
++        req.on('data', (c) => { body += c; });
++        req.on('end', () => {
++            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/agent-systems') return json(200, { agents: [{ id: 'openvibe-runtime' }] });
++            if (req.url === '/api/v1/agents/presets') return json(200, { presets: [{ id: 'researcher', name: 'Researcher' }] });
++            if (req.url === '/api/v1/agents' && req.method === 'GET') return json(200, { agents: [agent()] });
++            if (req.url === '/api/v1/agents' && req.method === 'POST') return json(201, agent({ name: 'Researcher' }));
++            if (req.url === `/api/v1/agents/${AGENT}/level` && req.method === 'PUT') return json(200, agent({ level: 'auto-edits' }));
++            if (req.url === `/api/v1/agents/${AGENT}` && req.method === 'PATCH') return json(200, agent({ name: 'Vibe 2' }));
++            if (req.url === `/api/v1/agents/${AGENT}` && req.method === 'DELETE') { res.writeHead(204); return res.end(); }
++            if (req.url === `/api/v1/agents/${AGENT}` && req.method === 'GET') return json(200, agent());
++            return json(404, { code: 'actor.agent.not_found' });
++        });
++    });
++    await new Promise((r) => server.listen(0, '127.0.0.1', r));
++    const base = `http://127.0.0.1:${server.address().port}`;
++    const actor = createActorClient(createClient({ baseUrls: { actor: base }, token: 'person-token' }));
++    try {
++        assert.deepStrictEqual(await actor.contacts.list(), { agents: [agent()] });
++        assert.deepStrictEqual(await actor.contacts.presets(), { presets: [{ id: 'researcher', name: 'Researcher' }] });
++        assert.deepStrictEqual(await actor.contacts.get(AGENT), agent());
++        const created = await actor.contacts.create({ preset: 'researcher', name: 'Researcher' });
++        assert.strictEqual(created.name, 'Researcher');
++        assert.deepStrictEqual(await actor.contacts.update(AGENT, { name: 'Vibe 2' }), agent({ name: 'Vibe 2' }));
++        assert.deepStrictEqual(await actor.contacts.setLevel(AGENT, 'auto-edits'), agent({ level: 'auto-edits' }));
++        await actor.contacts.remove(AGENT);
++        assert.deepStrictEqual(await actor.agents.catalog(), { agents: [{ id: 'openvibe-runtime' }] });
++        assert.deepStrictEqual(await actor.agents.list(), { agents: [{ id: 'openvibe-runtime' }] });
++
++        assert.deepStrictEqual(seen.map((s) => `${s.method} ${s.url}`), [
++            'GET /api/v1/agents', 'GET /api/v1/agents/presets', `GET /api/v1/agents/${AGENT}`,
++            'POST /api/v1/agents', `PATCH /api/v1/agents/${AGENT}`, `PUT /api/v1/agents/${AGENT}/level`,
++            `DELETE /api/v1/agents/${AGENT}`, 'GET /api/v1/agent-systems', 'GET /api/v1/agent-systems',
++        ]);
++        assert.ok(seen.every((s) => s.auth === 'Bearer person-token'), 'the person token rides every call');
++        assert.strictEqual(JSON.parse(seen[3].body).preset, 'researcher');
++        assert.deepStrictEqual(JSON.parse(seen[5].body), { level: 'auto-edits' });
++        assert.throws(() => actor.contacts.get('nope'), /agent id/);
++        console.log('  ok  actor contacts: list, presets, create, update, level, delete and the explicit catalog');
++    } finally {
++        await new Promise((r) => server.close(r));
++    }
++})().catch((err) => { console.error(err); process.exit(1); });
ddiff --git a/test/product-modules.test.js b/test/product-modules.test.js
iindex b5c4301..a093b95 100644
---- a/test/product-modules.test.js
++++ b/test/product-modules.test.js
@@@ -114,7 +114,7 @@ const ids = { plan: `pln_${ULID}`, task: `tsk_${ULID}`, agent: `agt_${ULID}`, me
          await actor.me.agents.memory.clear(ids.agent);
          const a = mark();
          assert.deepStrictEqual(a.map((r) => `${r.method} ${r.url}`), [
--            'GET /api/v1/agents', 'POST /api/v1/route', 'POST /api/v1/tasks', 'POST /api/v1/tasks', 'POST /api/v1/tasks',
++            'GET /api/v1/agent-systems', 'POST /api/v1/route', 'POST /api/v1/tasks', 'POST /api/v1/tasks', 'POST /api/v1/tasks',
              'GET /api/v1/tasks?limit=10', `GET /api/v1/tasks/${ids.task}`, `POST /api/v1/tasks/${ids.task}/cancel`, `POST /api/v1/tasks/${ids.task}/cancel`,
              `GET /api/v1/tasks/${ids.task}/events`, 'GET /api/v1/me/agents', 'POST /api/v1/me/agents', `GET /api/v1/me/agents/${ids.agent}`,
              `PATCH /api/v1/me/agents/${ids.agent}`, `PATCH /api/v1/me/agents/${ids.agent}`, `DELETE /api/v1/me/agents/${ids.agent}`, `DELETE /api/v1/me/agents/${ids.agent}`,
ddiff --git a/types/actor.d.ts b/types/actor.d.ts
iindex 0196ed7..3600fbc 100644
---- a/types/actor.d.ts
++++ b/types/actor.d.ts
@@@ -2,13 +2,33 @@
  type Opts = { signal?: AbortSignal };
  type ActorJson = Record<string, any>;
  export type ActorMode = 'cheapest' | 'balanced' | 'best' | 'fastest' | 'private';
++export type ActorLevel = 'ask' | 'auto-edits' | 'approve-for-me' | 'full';
++export interface ActorAgentModel { engine: 'runtime' | 'own-keys' | 'open-gpu' | 'link'; model: string }
++export interface ActorAgentComputer { kind: 'browser' | 'kept-browser' | 'desktop' | 'gpu-desktop' | 'always-on' | 'your-computer' | 'throwaway'; placement: 'auto' | 'link' | 'home' | 'ovh' }
++export interface ActorAgent {
++    id: string; owner: string; name: string; face: string; voice: string | null; model: ActorAgentModel;
++    computer: ActorAgentComputer | null; apps: string[]; memory: string | null; level: ActorLevel; created_at: string;
++}
++export interface ActorAgentWrite {
++    preset?: 'researcher' | 'inbox' | 'studio-editor' | 'party-host'; name?: string; face?: string; voice?: string | null;
++    model?: ActorAgentModel; computer?: ActorAgentComputer | null; apps?: string[]; memory?: string | null; level?: ActorLevel;
++}
  export interface TaskRequest {
--    task: string; mode?: ActorMode; budget?: { per_task_usd?: number; per_day_usd?: number }; agent?: string; idempotency_key?: string;
++    task: string; mode?: ActorMode; budget?: { per_task_usd?: number; per_day_usd?: number }; agent?: string; agent_id?: string; level?: ActorLevel; idempotency_key?: string;
      webhooks?: Array<{ url: string; events?: string[]; secret_ref?: string }>; [k: string]: unknown;
  }
  export interface TaskEvent { id: number | null; event: string; data: any }
  export interface ActorClient {
--    agents: { list(opts?: Opts): Promise<{ agents: ActorJson[] }> };
++    agents: { catalog(opts?: Opts): Promise<{ agents: ActorJson[] }>; list(opts?: Opts): Promise<{ agents: ActorJson[] }> };
++    contacts: {
++        list(opts?: Opts): Promise<{ agents: ActorAgent[] }>;
++        presets(opts?: Opts): Promise<{ presets: ActorJson[] }>;
++        get(id: string, opts?: Opts): Promise<ActorAgent>;
++        create(agent: ActorAgentWrite, opts?: Opts): Promise<ActorAgent>;
++        update(id: string, patch: ActorAgentWrite, opts?: Opts): Promise<ActorAgent>;
++        remove(id: string, opts?: Opts): Promise<ActorJson>;
++        setLevel(id: string, level: ActorLevel, extra?: { agent_id?: string; thread_id?: string; reason?: string }, opts?: Opts): Promise<ActorAgent>;
++    };
      route(req: { task: string; mode?: ActorMode; agent?: string }, opts?: Opts): Promise<ActorJson>;
      tasks: {
          create(req: TaskRequest, opts?: Opts): Promise<ActorJson & { id: string; webhook_secret?: string }>;