@tokensmind/agent-network 0.1.0

package/skills/tokensmind-agent-network-runtime/scripts/lib/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/skills/tokensmind-agent-network-runtime/scripts/lib/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/skills/tokensmind-agent-network-runtime/scripts/lib/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/skills/tokensmind-agent-network-runtime/scripts/lib/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();
+        });
+      });
+    },
+  };
+}

package/skills/tokensmind-agent-network-runtime/scripts/lib/runtime/connector.js

@@ -0,0 +1,204 @@
+import { randomUUID } from 'node:crypto';
+import { AgentNetworkHttpError } from './httpClient.js';
+import {
+  createPendingAuthorization,
+  createRemoteAuthorization,
+  exchangeAuthorization,
+  waitForApproval,
+} from './deviceAuthorization.js';
+import {
+  buildBusinessUrl,
+  isPublicDiscoveryRequest,
+  validateBusinessRequest,
+} from './requestPolicy.js';
+
+function requestHeaders({ token, idempotencyKey }) {
+  return {
+    'Content-Type': 'application/json',
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+  };
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
+  );
+}
+
+function operationsMatch(left, right) {
+  return JSON.stringify(canonicalize(left)) === JSON.stringify(canonicalize(right));
+}
+
+function assertPendingMatches(pending, operation) {
+  if (!operationsMatch(pending.operation, operation)) {
+    throw new Error(
+      'A different Agent Network operation is pending; retry the original operation first',
+    );
+  }
+}
+
+function assertActiveCredential(active) {
+  if (!active?.token) {
+    throw new Error('Authorized Agent Network operation has no active stored credential');
+  }
+  return active;
+}
+
+function authorizationPending(verificationUrl) {
+  const error = new Error(
+    'Complete Agent Network authorization in the browser, then retry the action.',
+  );
+  error.status = 'authorization_required';
+  error.verificationUrl = verificationUrl;
+  return error;
+}
+
+async function executeBusinessRequest({ operation, token, baseUrl, http, signal }) {
+  return http.request({
+    url: buildBusinessUrl(baseUrl, operation.path),
+    method: operation.method,
+    headers: requestHeaders({ token, idempotencyKey: operation.idempotencyKey }),
+    body: operation.body,
+    signal,
+  });
+}
+
+async function loadInstanceId(store) {
+  const existing = await store.read('instance');
+  if (existing?.id) return existing.id;
+  const id = randomUUID();
+  await store.write('instance', { id });
+  return id;
+}
+
+async function preparePending({ operation, store }) {
+  const existing = await store.read('pending');
+  if (existing) return existing;
+  const instanceId = await loadInstanceId(store);
+  const pending = createPendingAuthorization({ operation, instanceId });
+  await store.write('pending', pending);
+  return pending;
+}
+
+async function authorize({ operation, store, browser, baseUrl, http, client, signal }) {
+  try {
+    let pending = await preparePending({ operation, store });
+    if (pending.phase === 'prepared') {
+      pending = await createRemoteAuthorization({ pending, baseUrl, http, client, signal });
+      await store.write('pending', pending);
+      await browser.open(pending.authorization.verificationUrl);
+      throw authorizationPending(pending.authorization.verificationUrl);
+    }
+    if (pending.phase === 'authorizing') {
+      await waitForApproval({ pending, baseUrl, http, signal });
+      const exchange = await exchangeAuthorization({ pending, baseUrl, http, signal });
+      const active = {
+        token: pending.token,
+        agentId: exchange.agent?.id || null,
+        credentialId: exchange.credential.id,
+        tokenPrefix: exchange.credential.tokenPrefix,
+      };
+      await store.write('active', active);
+      pending = { ...pending, phase: 'authorized' };
+      await store.write('pending', pending);
+      return active;
+    }
+    return store.read('active');
+  } catch (error) {
+    if (isTerminalAuthorizationError(error)) await store.remove('pending');
+    throw error;
+  }
+}
+
+function isTerminalAuthorizationError(error) {
+  return error instanceof AgentNetworkHttpError
+    && [
+      'DEVICE_AUTHORIZATION_DENIED',
+      'DEVICE_AUTHORIZATION_EXCHANGED',
+      'DEVICE_AUTHORIZATION_EXPIRED',
+    ].includes(error.code);
+}
+
+function isInvalidAgentCredential(error) {
+  return error instanceof AgentNetworkHttpError
+    && [
+      'AGENT_CREDENTIAL_EXPIRED',
+      'AGENT_CREDENTIAL_INVALID',
+      'AGENT_CREDENTIAL_REVOKED',
+    ].includes(error.code);
+}
+
+async function executeAndFinalize({ pending, active, dependencies }) {
+  assertActiveCredential(active);
+  try {
+    const result = await executeBusinessRequest({
+      operation: pending.operation,
+      token: active.token,
+      ...dependencies,
+    });
+    await dependencies.store.remove('pending');
+    return result;
+  } catch (error) {
+    if (error instanceof AgentNetworkHttpError && error.status < 500 && error.status !== 429) {
+      await dependencies.store.remove('pending');
+      if (isInvalidAgentCredential(error)) await dependencies.store.remove('active');
+    }
+    throw error;
+  }
+}
+
+export function createConnector({ store, browser, baseUrl, http, client }) {
+  let executionQueue = Promise.resolve();
+
+  const dependencies = (signal) => ({ store, browser, baseUrl, http, client, signal });
+
+  async function authorizeAndExecute(operation, signal) {
+    const active = await authorize({ operation, ...dependencies(signal) });
+    const pending = await store.read('pending');
+    return executeAndFinalize({ pending, active, dependencies: dependencies(signal) });
+  }
+
+  async function resumePending(pending, operation, signal) {
+    assertPendingMatches(pending, operation);
+    return authorizeAndExecute(pending.operation, signal);
+  }
+
+  async function executeWithActive(operation, active, signal) {
+    try {
+      return await executeBusinessRequest({ operation, token: active.token, baseUrl, http, signal });
+    } catch (error) {
+      if (!isInvalidAgentCredential(error)) throw error;
+      await store.remove('active');
+      return authorizeAndExecute(operation, signal);
+    }
+  }
+
+  async function executeOnce(params, { signal } = {}) {
+    if (signal?.aborted) throw signal.reason;
+    const normalized = validateBusinessRequest(params);
+    const operation = { ...normalized, body: params.body };
+    const reauthorize = params.reauthorize === true;
+    const pending = await store.read('pending');
+    const active = await store.read('active');
+
+    if (pending) return resumePending(pending, operation, signal);
+
+    if (isPublicDiscoveryRequest(operation) && !reauthorize) {
+      return executeBusinessRequest({ operation, baseUrl, http, signal });
+    }
+
+    if (!active || reauthorize) return authorizeAndExecute(operation, signal);
+    return executeWithActive(operation, active, signal);
+  }
+
+  return {
+    execute(params, options) {
+      const result = executionQueue.then(() => executeOnce(params, options));
+      executionQueue = result.catch(() => undefined);
+      return result;
+    },
+  };
+}

package/skills/tokensmind-agent-network-runtime/scripts/lib/runtime/constants.js

@@ -0,0 +1,10 @@
+export const DEFAULT_BASE_URL = 'https://tokensmind.ai';
+export const DEVICE_CODE_PREFIX = 'tm_device_';
+export const AGENT_TOKEN_PREFIX = 'tm_agent_';
+export const DEVICE_AUTHORIZATION_PATH = '/agent-network-api/device-authorizations';
+export const MUTATION_METHODS = new Set(['POST', 'PATCH', 'DELETE']);
+
+export const INTERNAL_PATH_PATTERNS = [
+  /^\/agent-network-api\/device-authorizations(?:\/|$)/,
+  /^\/agent-network-api\/agents\/[^/]+\/credentials(?:\/|$)/,
+];

package/skills/tokensmind-agent-network-runtime/scripts/lib/runtime/credentialStore.js

@@ -0,0 +1,162 @@
+import { isDeepStrictEqual } from 'node:util';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  createPortableStore,
+  originNamespace,
+  resolvePortableStateDir,
+} from './portableStore.js';
+import { resolveSystemCredentialStore } from './systemCredentialStore.js';
+
+const RECORD_NAMES = Object.freeze(['instance', 'pending', 'active']);
+
+function requireHome(homeDir) {
+  const home = String(homeDir || '').trim();
+  if (!home) throw new Error('Unable to resolve the current user home directory');
+  return home;
+}
+
+function windowsLegacyDirs(env) {
+  const localAppData = String(env.LOCALAPPDATA || '').trim();
+  return localAppData ? [path.win32.join(localAppData, 'TokensMind', 'AgentNetwork')] : [];
+}
+
+function linuxLegacyDirs({ env, home }) {
+  const defaultDirectory = path.join(home, '.local', 'state', 'tokensmind', 'agent-network');
+  const xdgStateHome = String(env.XDG_STATE_HOME || '').trim();
+  if (!xdgStateHome) return [defaultDirectory];
+  return [...new Set([
+    path.join(xdgStateHome, 'tokensmind', 'agent-network'), defaultDirectory,
+  ])];
+}
+
+export function resolveLegacyStateDirs({
+  platform = process.platform,
+  env = process.env,
+  homeDir = os.homedir(),
+} = {}) {
+  const home = requireHome(homeDir);
+  if (platform === 'darwin') {
+    return [path.join(home, 'Library', 'Application Support', 'TokensMind', 'AgentNetwork')];
+  }
+  if (platform === 'win32') return windowsLegacyDirs(env);
+  if (platform !== 'linux') return [];
+  return linuxLegacyDirs({ env, home });
+}
+
+async function collectSourceRecords(sources) {
+  const candidates = new Map();
+  for (const source of sources) {
+    for (const name of RECORD_NAMES) {
+      const value = await source.read(name);
+      if (value === null) continue;
+      const candidate = candidates.get(name);
+      if (candidate && !isDeepStrictEqual(candidate.value, value)) {
+        throw new Error(`Conflicting Agent Network ${name} records exist in known local stores`);
+      }
+      if (candidate) candidate.sources.push(source);
+      else candidates.set(name, { value, sources: [source] });
+    }
+  }
+  return candidates;
+}
+
+async function validateMigrationTarget(target, candidates) {
+  const missing = [];
+  for (const [name, candidate] of candidates) {
+    const current = await target.read(name);
+    if (current === null) missing.push([name, candidate.value]);
+    else if (!isDeepStrictEqual(current, candidate.value)) {
+      throw new Error(`Stored Agent Network ${name} conflicts with a known legacy record`);
+    }
+  }
+  return missing;
+}
+
+async function verifyWrites(target, records) {
+  for (const [name, expected] of records) {
+    const actual = await target.read(name);
+    if (!isDeepStrictEqual(actual, expected)) {
+      throw new Error(`Agent Network ${name} migration could not be verified`);
+    }
+  }
+}
+
+async function removeMigratedSources(candidates) {
+  for (const [name, candidate] of candidates) {
+    for (const source of candidate.sources) await source.remove(name);
+  }
+}
+
+export async function migrateCredentialStores({ target, sources }) {
+  const candidates = await collectSourceRecords(sources);
+  if (candidates.size === 0) return;
+  const missing = await validateMigrationTarget(target, candidates);
+  for (const [name, value] of missing) await target.write(name, value);
+  await verifyWrites(target, [...candidates].map(([name, item]) => [name, item.value]));
+  await removeMigratedSources(candidates);
+}
+
+function createLazyStore(resolveStore) {
+  let storePromise;
+  const getStore = () => {
+    storePromise ||= resolveStore();
+    return storePromise;
+  };
+  return {
+    async read(name) {
+      return (await getStore()).read(name);
+    },
+    async write(name, value) {
+      return (await getStore()).write(name, value);
+    },
+    async remove(name) {
+      return (await getStore()).remove(name);
+    },
+  };
+}
+
+function createFileStores({ directories, origin, platform, env, homeDir, fs, randomId }) {
+  return directories.map((stateDir) => createPortableStore({
+    stateDir, origin, platform, env, homeDir, fs, randomId,
+  }));
+}
+
+export function createCredentialStore({
+  stateDir,
+  origin,
+  platform = process.platform,
+  env = process.env,
+  homeDir = os.homedir(),
+  fs,
+  randomId,
+  secureStore,
+  resolveSecureStore = resolveSystemCredentialStore,
+  run,
+} = {}) {
+  if (stateDir) {
+    return createPortableStore({ stateDir, origin, platform, env, homeDir, fs, randomId });
+  }
+  const fallbackDirectory = resolvePortableStateDir({ platform, env, homeDir });
+  const fallback = createPortableStore({
+    stateDir: fallbackDirectory, origin, platform, env, homeDir, fs, randomId,
+  });
+  return createLazyStore(async () => {
+    const systemStore = secureStore === undefined
+      ? await resolveSecureStore({
+        platform, namespace: originNamespace(origin), env, fs, run,
+      })
+      : secureStore;
+    const target = systemStore || fallback;
+    const sourceDirectories = [
+      ...(systemStore ? [fallbackDirectory] : []),
+      ...resolveLegacyStateDirs({ platform, env, homeDir }),
+    ];
+    const sources = createFileStores({
+      directories: [...new Set(sourceDirectories)],
+      origin, platform, env, homeDir, fs, randomId,
+    });
+    await migrateCredentialStores({ target, sources });
+    return target;
+  });
+}