@cognitiondesk/agent-runtime

Agent execution runtime for CognitionDesk. Wraps @cognitiondesk/client with agent CRUD, model selection, invocation, streaming, and usage metrics.

Tier 2 package — builds on @cognitiondesk/client (optional peer dep). Uses no @mounaji_npm/* packages, keeping it reusable by any consumer.

Install

npm install @cognitiondesk/agent-runtime

If you want real backend calls (not mock mode), also install the SDK:

npm install @cognitiondesk/agent-runtime @cognitiondesk/client

Quick start

import { createAgentRuntime } from '@cognitiondesk/agent-runtime';

const runtime = await createAgentRuntime({
  backendUrl: 'https://api.cognitiondesk.com',
  authToken: firebaseToken,   // or apiKey
});

const agents  = await runtime.listAgents();
const agent   = await runtime.createAgent({ name: 'Copilot', model: 'gpt-4o' });
const reply   = await runtime.invokeAgent(agent.id, 'Summarize this document');
const models  = await runtime.listModels();
const usage   = await runtime.getUsage();

API

createAgentRuntime(opts) → Promise<AgentRuntime>

| Option | Type | Description | |---|---|---| | backendUrl | string | CognitionDesk backend URL | | authToken | string | Firebase bearer token | | apiKey | string | CognitionDesk API key | | getAuthToken | () => Promise<string> | Async token provider | | getApiKey | () => Promise<string> | Async key provider | | mock | boolean | Force mock mode (no backend) |

AgentRuntime methods

| Method | Returns | Description | |---|---|---| | listAgents() | AgentActor[] | All agents for the current user | | listSystemAgents() | AgentActor[] | Pre-built system agents | | getAgent(id) | AgentActor \| null | Single agent by ID | | createAgent(data) | AgentActor | Create a new agent | | updateAgent(id, updates) | AgentActor | Full update | | patchAgent(id, updates) | AgentActor | Partial update | | listModels() | Model[] | Available models from catalog | | getProviderConfig() | object | Masked provider config | | setProviderConfig(config) | object | Update provider config | | invokeAgent(id, prompt, opts) | string | Invoke agent, get text | | streamAgent(id, prompt, opts) | AsyncGenerator | Stream agent events | | getUsage() | object | Current usage + plan | | getUsageMetrics(params) | object | Metrics with model breakdown | | listWorkflows(filters) | Workflow[] | List workflows | | createWorkflow(data) | Workflow | Create a workflow | | listTasks(filters) | Task[] | List tasks | | createTask(data) | Task | Create a task | | updateTask(id, updates) | Task | Update a task |

toAgentActor(assistant) → AgentActor

Converts a CognitionDesk assistant to a neutral AgentActor shape (compatible with @mounaji_npm/forum-contracts Actor model but does not depend on it).

Mock mode

If @cognitiondesk/client is not installed, the runtime automatically falls back to mock mode with demo data. This lets you develop without a backend.

const runtime = await createAgentRuntime({ mock: true });
const agents = await runtime.listAgents(); // 3 demo agents

Architecture

This package is Tier 2 in the three-tier model:

Tier 1 — @mounaji_npm/*          (base: tokens, ui, auth, forum, contracts)
Tier 2 — @cognitiondesk/*        (this package + client, widget, orchestration, skills)
Tier 3 — apps (ai-forum-app, mounaji-platform, ...)

Dependency rules:

• Depends on @cognitiondesk/client (optional peer dep).
• Does not depend on any @mounaji_npm/* package.
• Consumers map the neutral AgentActor shape to their own actor schema if needed.

License

MIT