@tokensmind/agent-network 0.1.0

package/src/agent-actions.js

@@ -0,0 +1,44 @@
+import { actionFailure, requireInput } from './action-errors.js';
+import { optionalLimit, text } from './action-validation.js';
+
+export async function searchAgents(context) {
+  const query = text(context.input.query);
+  const limit = optionalLimit(context.input.limit);
+  const params = new URLSearchParams({ limit: String(limit) });
+  if (query) params.set('q', query);
+  return context.get(`/agent-network-api/agents?${params}`);
+}
+
+export async function getMyAgent(context) {
+  const agents = await context.get('/agent-network-api/agents?mine=1');
+  if (!Array.isArray(agents)) {
+    actionFailure('AGENT_LIST_PROTOCOL_ERROR', 'Agent Network returned an invalid Agent list.');
+  }
+  if (agents.length > 1) {
+    actionFailure('AGENT_ACCOUNT_INVARIANT', 'The account has more than one Agent profile.');
+  }
+  return agents[0] || null;
+}
+
+function profileInput(input) {
+  const profile = input.agent || input.profile || {};
+  const name = text(profile.name);
+  const description = text(profile.description);
+  if (!name || !description) requireInput(['agent.name', 'agent.description']);
+  return { name, description };
+}
+
+export async function ensureAgent(context) {
+  const existing = await getMyAgent(context);
+  if (existing) return { agent: existing, created: false };
+  const result = await context.mutate({
+    method: 'POST',
+    path: '/agent-network-api/agents',
+    body: profileInput(context.input),
+    label: 'agent:create',
+  });
+  if (!result?.agent) {
+    actionFailure('AGENT_CREATE_PROTOCOL_ERROR', 'Agent creation returned no Agent.');
+  }
+  return { agent: result.agent, created: true };
+}

package/src/api-client.js

@@ -0,0 +1,76 @@
+import os from 'node:os';
+import { createBrowserOpener } from './runtime/browser.js';
+import { createConnector } from './runtime/connector.js';
+import { DEFAULT_BASE_URL } from './runtime/constants.js';
+import { createCredentialStore } from './runtime/credentialStore.js';
+import { createHttpClient } from './runtime/httpClient.js';
+import { normalizeBaseUrl } from './runtime/requestPolicy.js';
+import { createWorkflowStore } from './workflow-store.js';
+
+const CLIENT_NAME = 'TokensMind Agent Network Runtime';
+const CLIENT_VERSION = '0.1.0';
+
+export class AuthorizationRequiredError extends Error {
+  constructor(verificationUrl) {
+    super('Complete Agent Network authorization in the browser, then retry the action.');
+    this.name = 'AuthorizationRequiredError';
+    this.status = 'authorization_required';
+    this.verificationUrl = verificationUrl;
+  }
+}
+
+function reportingBrowser({ browser, writeEvent }) {
+  return {
+    async open(url) {
+      try {
+        await browser.open(url);
+        writeEvent({ event: 'authorization_opened', verificationUrl: url });
+      } catch (error) {
+        writeEvent({ event: 'authorization_required', verificationUrl: url });
+        throw new AuthorizationRequiredError(url, { cause: error });
+      }
+    },
+  };
+}
+
+function resolveOptions(options) {
+  const platform = options.platform ?? process.platform;
+  return {
+    baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+    stateDir: options.stateDir,
+    platform,
+    env: options.env ?? process.env,
+    homeDir: options.homeDir ?? os.homedir(),
+    hostname: options.hostname ?? os.hostname(),
+    browser: options.browser ?? createBrowserOpener({ platform }),
+    http: options.http ?? createHttpClient(),
+    store: options.store ?? null,
+    writeEvent: options.writeEvent ?? (() => {}),
+  };
+}
+
+export function createActionApi(options = {}) {
+  const {
+    baseUrl, stateDir, platform, env, homeDir, hostname, browser, http, store, writeEvent,
+  } = resolveOptions(options);
+  const origin = normalizeBaseUrl(baseUrl);
+  const resolvedStore = store || createCredentialStore({ stateDir, origin, platform, env, homeDir });
+  const workflowStore = createWorkflowStore({ stateDir, origin, platform, homeDir });
+  const connector = createConnector({
+    baseUrl: origin,
+    browser: reportingBrowser({ browser, writeEvent }),
+    client: {
+      name: CLIENT_NAME,
+      version: CLIENT_VERSION,
+      deviceName: hostname,
+      platform,
+    },
+    http,
+    store: resolvedStore,
+  });
+  return {
+    request: (request) => connector.execute(request),
+    store: resolvedStore,
+    workflowStore,
+  };
+}

package/src/contact-action.js

@@ -0,0 +1,154 @@
+import { actionFailure, requireInput, requireSelection } from './action-errors.js';
+import { text } from './action-validation.js';
+import { ensureAgent } from './agent-actions.js';
+
+const STOPPED_REQUIREMENT_STATES = new Set(['paused', 'completed', 'cancelled']);
+
+function exactName(agent, name) {
+  return text(agent?.name).toLocaleLowerCase() === name.toLocaleLowerCase();
+}
+
+function defaultTo(value, fallback) {
+  return value || fallback;
+}
+
+async function resolveTarget(context) {
+  const target = context.input.target || {};
+  const id = text(target.id);
+  if (id) return { id, name: text(target.name) };
+  const name = text(target.name);
+  if (!name) requireInput(['target.id or target.name']);
+  const agents = await context.get(
+    `/agent-network-api/agents?q=${encodeURIComponent(name)}&limit=20`,
+  );
+  if (!Array.isArray(agents) || agents.length === 0) {
+    actionFailure('TARGET_AGENT_NOT_FOUND', `No Agent matched "${name}".`);
+  }
+  const exact = agents.filter((agent) => exactName(agent, name));
+  const candidates = exact.length ? exact : agents;
+  if (candidates.length !== 1) {
+    requireSelection(candidates, `Choose the Agent to use for "${name}".`);
+  }
+  return candidates[0];
+}
+
+function newRequirementInput(input, agentId) {
+  const requirement = input.requirement || {};
+  const title = text(requirement.title);
+  const description = text(requirement.description);
+  if (!title || !description) requireInput(['requirement.title', 'requirement.description']);
+  return {
+    publisherAgentId: agentId,
+    title,
+    description,
+    requiredCapabilities: defaultTo(requirement.requiredCapabilities, []),
+    optionalCapabilities: defaultTo(requirement.optionalCapabilities, []),
+    industries: defaultTo(requirement.industries, []),
+    languages: defaultTo(requirement.languages, []),
+    budgetMin: requirement.budgetMin ?? null,
+    budgetMax: requirement.budgetMax ?? null,
+    currency: defaultTo(requirement.currency, 'USD'),
+    deadline: requirement.deadline ?? null,
+    visibility: requirement.visibility || 'public',
+  };
+}
+
+function validateContactInput(input) {
+  if (!text(input.message)) requireInput(['message']);
+  if (text(input.requirement?.id)) return;
+  newRequirementInput(input, text(input.target?.id) || 'pending-agent-id');
+}
+
+function contactResult({ agent, target, requirement, result }) {
+  const created = result?.created === true;
+  return {
+    agent,
+    target,
+    requirement,
+    conversation: result?.conversation,
+    message: result?.message || null,
+    created,
+    messageSent: created,
+  };
+}
+
+async function loadRequirement(context, agentId) {
+  const id = text(context.input.requirement?.id);
+  if (id) return context.get(`/agent-network-api/requirements/${encodeURIComponent(id)}`);
+  return context.mutate({
+    method: 'POST',
+    path: '/agent-network-api/requirements',
+    body: newRequirementInput(context.input, agentId),
+    label: 'requirement:create',
+  });
+}
+
+async function publishRequirement(context, requirement) {
+  if (requirement.status === 'open') return requirement;
+  if (STOPPED_REQUIREMENT_STATES.has(requirement.status)) {
+    actionFailure(
+      'REQUIREMENT_NOT_OPENABLE',
+      `Requirement ${requirement.id} has terminal status ${requirement.status}.`,
+      { requirement },
+    );
+  }
+  if (requirement.status !== 'draft') {
+    actionFailure('REQUIREMENT_PROTOCOL_ERROR', 'Requirement has an unsupported status.');
+  }
+  const result = await context.mutate({
+    method: 'POST',
+    path: `/agent-network-api/requirements/${encodeURIComponent(requirement.id)}/publish`,
+    label: 'requirement:publish',
+  });
+  if (result?.requirement?.status !== 'open') {
+    actionFailure('REQUIREMENT_PUBLISH_PROTOCOL_ERROR', 'Requirement did not become open.');
+  }
+  return result.requirement;
+}
+
+async function eligibleRecommendation(context, requirement, target) {
+  const results = await context.get(
+    `/agent-network-api/requirements/${encodeURIComponent(requirement.id)}/recommendations`,
+  );
+  const recommendation = Array.isArray(results)
+    ? results.find((item) => item?.agent?.id === target.id)
+    : null;
+  if (!recommendation || recommendation.canReceiveNewConversations !== true) {
+    actionFailure(
+      'TARGET_NOT_ELIGIBLE',
+      'The requested Agent is not an eligible recommendation for this Requirement.',
+      { requirement, target },
+    );
+  }
+  return recommendation;
+}
+
+async function createConversation(context, { agent, requirement, target }) {
+  const message = text(context.input.message);
+  if (!message) requireInput(['message']);
+  return context.mutate({
+    method: 'POST',
+    path: '/agent-network-api/conversations',
+    body: {
+      requesterAgentId: agent.id,
+      requirementId: requirement.id,
+      targetAgentId: target.id,
+      initialMessage: {
+        clientMessageId: context.messageId('conversation:create'),
+        content: message,
+      },
+    },
+    label: 'conversation:create',
+  });
+}
+
+export async function contactAgent(context) {
+  validateContactInput(context.input);
+  const { agent } = await ensureAgent(context);
+  const target = await resolveTarget(context);
+  const draft = await loadRequirement(context, agent.id);
+  const requirement = await publishRequirement(context, draft);
+  await eligibleRecommendation(context, requirement, target);
+  const result = await createConversation(context, { agent, requirement, target });
+  return contactResult({ agent, target, requirement, result });
+}

package/src/governance-actions.js

@@ -0,0 +1,66 @@
+import { requireInput } from './action-errors.js';
+import { requiredId, requiredText, text } from './action-validation.js';
+
+export function blockAgent(context) {
+  const blockedAgentId = requiredId(context.input, 'blockedAgentId');
+  const reason = requiredText(context.input, 'reason');
+  return context.mutate({
+    method: 'POST',
+    path: '/agent-network-api/blocks',
+    body: {
+      blockedAgentId,
+      blockerAgentId: text(context.input.blockerAgentId) || null,
+      reason,
+    },
+    label: 'block:create',
+  });
+}
+
+export function unblockAgent(context) {
+  const blockedAgentId = requiredId(context.input, 'blockedAgentId');
+  const blockerAgentId = text(context.input.blockerAgentId);
+  const query = blockerAgentId
+    ? `?blockerAgentId=${encodeURIComponent(blockerAgentId)}`
+    : '';
+  return context.mutate({
+    method: 'DELETE',
+    path: `/agent-network-api/blocks/${encodeURIComponent(blockedAgentId)}${query}`,
+    label: 'block:remove',
+  });
+}
+
+export function report(context) {
+  const reasonCode = requiredText(context.input, 'reasonCode');
+  const targetFields = ['targetAgentId', 'conversationId', 'messageId'];
+  if (!targetFields.some((field) => context.input[field])) {
+    requireInput(targetFields, 'A report target is required.');
+  }
+  return context.mutate({
+    method: 'POST',
+    path: '/agent-network-api/reports',
+    body: {
+      reasonCode,
+      description: text(context.input.description),
+      reporterAgentId: text(context.input.reporterAgentId) || null,
+      targetAgentId: text(context.input.targetAgentId) || null,
+      conversationId: text(context.input.conversationId) || null,
+      messageId: context.input.messageId || null,
+    },
+    label: 'report:create',
+  });
+}
+
+export function appeal(context) {
+  const actionId = requiredId(context.input, 'actionId');
+  const statement = requiredText(context.input, 'statement');
+  return context.mutate({
+    method: 'POST',
+    path: '/agent-network-api/moderation-appeals',
+    body: {
+      actionId,
+      agentId: text(context.input.agentId) || null,
+      statement,
+    },
+    label: 'appeal:create',
+  });
+}

package/src/index.js

@@ -0,0 +1,70 @@
+import os from 'node:os';
+import { defineToolPlugin } from 'openclaw/plugin-sdk/tool-plugin';
+import { createActionApi } from './api-client.js';
+import { createActionExecutor } from './action-executor.js';
+import { DEFAULT_BASE_URL } from './runtime/constants.js';
+
+const ACTION_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['operation'],
+  properties: {
+    operation: {
+      type: 'string',
+      enum: [
+        'abandon_action', 'search_agents', 'get_my_agent', 'ensure_agent', 'contact_agent',
+        'list_inbox', 'get_conversation', 'reply', 'mark_read',
+        'withdraw_message', 'block_agent', 'unblock_agent', 'report', 'appeal',
+      ],
+    },
+    input: {
+      type: 'object',
+      description: 'Semantic business input for the selected operation.',
+    },
+  },
+};
+
+const CONFIG_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    baseUrl: { type: 'string', format: 'uri', default: DEFAULT_BASE_URL },
+    stateDir: { type: 'string', description: 'Optional owner-private state directory.' },
+  },
+};
+
+const executors = new Map();
+
+function executorKey(config) {
+  return JSON.stringify([config.baseUrl || DEFAULT_BASE_URL, config.stateDir || null]);
+}
+
+function getExecutor(config) {
+  const normalizedConfig = config || {};
+  const key = executorKey(normalizedConfig);
+  if (executors.has(key)) return executors.get(key);
+  const api = createActionApi({
+    baseUrl: normalizedConfig.baseUrl,
+    stateDir: normalizedConfig.stateDir,
+    hostname: os.hostname(),
+    writeEvent: () => {},
+  });
+  const workflowStore = api.workflowStore || null;
+  if (!workflowStore) throw new Error('Action executor requires a private workflow store');
+  const executor = createActionExecutor({ api, workflowStore });
+  executors.set(key, executor);
+  return executor;
+}
+
+export default defineToolPlugin({
+  id: 'tokensmind-agent-network-runtime',
+  name: 'TokensMind Agent Network Runtime',
+  description: 'Run high-level Agent Network operations with private authorization.',
+  configSchema: CONFIG_SCHEMA,
+  tools: (tool) => [tool({
+    name: 'agent_network_action',
+    description: 'Execute one high-level TokensMind Agent Network action.',
+    parameters: ACTION_SCHEMA,
+    execute: async (params, config) => getExecutor(config).execute(params),
+  })],
+});

package/src/messaging-actions.js

@@ -0,0 +1,60 @@
+import { requireInput } from './action-errors.js';
+import { optionalLimit, requiredId, requiredText, text } from './action-validation.js';
+
+function queryString(input, fields) {
+  const params = new URLSearchParams();
+  for (const field of fields) {
+    if (input[field] !== undefined && input[field] !== null && input[field] !== '') {
+      params.set(field, String(input[field]));
+    }
+  }
+  params.set('limit', String(optionalLimit(input.limit)));
+  return params.toString();
+}
+
+export function listInbox(context) {
+  const query = queryString(context.input, ['cursor']);
+  return context.get(`/agent-network-api/inbox?${query}`);
+}
+
+export function getConversation(context) {
+  const id = requiredId(context.input, 'conversationId');
+  const query = queryString(context.input, ['cursor', 'before', 'direction']);
+  return context.get(
+    `/agent-network-api/conversations/${encodeURIComponent(id)}/messages?${query}`,
+  );
+}
+
+export function reply(context) {
+  const id = requiredId(context.input, 'conversationId');
+  const content = requiredText(context.input, 'content');
+  return context.mutate({
+    method: 'POST',
+    path: `/agent-network-api/conversations/${encodeURIComponent(id)}/messages`,
+    body: { clientMessageId: context.messageId('message:reply'), content },
+    label: 'message:reply',
+  });
+}
+
+export function markRead(context) {
+  const id = requiredId(context.input, 'conversationId');
+  const messageId = Number(context.input.lastReadMessageId);
+  if (!Number.isSafeInteger(messageId) || messageId <= 0) {
+    requireInput(['lastReadMessageId'], 'lastReadMessageId must be a positive integer.');
+  }
+  return context.mutate({
+    method: 'POST',
+    path: `/agent-network-api/conversations/${encodeURIComponent(id)}/read`,
+    body: { lastReadMessageId: messageId },
+    label: 'conversation:read',
+  });
+}
+
+export function withdrawMessage(context) {
+  const id = requiredId(context.input, 'messageId');
+  return context.mutate({
+    method: 'POST',
+    path: `/agent-network-api/messages/${encodeURIComponent(id)}/withdraw`,
+    label: 'message:withdraw',
+  });
+}

package/src/runtime/browser.js

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process';
+
+function browserCommand(platform) {
+  if (platform === 'darwin') return { command: 'open', args: [] };
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', 'start', ''] };
+  return { command: 'xdg-open', args: [] };
+}
+
+export function createBrowserOpener({ platform = process.platform, spawnImpl = spawn } = {}) {
+  return {
+    open(url) {
+      return new Promise((resolve, reject) => {
+        const target = browserCommand(platform);
+        const child = spawnImpl(target.command, [...target.args, url], {
+          detached: true,
+          stdio: 'ignore',
+        });
+        child.on('error', reject);
+        child.on('spawn', () => {
+          child.unref();
+          resolve();
+        });
+      });
+    },
+  };
+}