@tokensmind/agent-network 0.1.0

package/skills/tokensmind-agent-network-runtime/scripts/python_runtime/portable_store.py

@@ -0,0 +1,195 @@
+import json
+import os
+import re
+import tempfile
+from datetime import datetime
+from hashlib import sha256
+from pathlib import Path
+from urllib.parse import urlsplit
+
+DIRECTORY_MODE = 0o700
+FILE_MODE = 0o600
+RECORD_NAMES = frozenset(("active", "pending", "instance"))
+PENDING_PHASES = frozenset(("prepared", "authorizing", "authorized"))
+UUID_PATTERN = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", re.I)
+SHA256_PATTERN = re.compile(r"^[a-f0-9]{64}$")
+DEVICE_CODE_PATTERN = re.compile(r"^tm_device_[A-Za-z0-9_-]{43}$")
+AGENT_TOKEN_PATTERN = re.compile(r"^tm_agent_[A-Za-z0-9_-]{43}$")
+
+
+def _require_home_directory(home_dir):
+    value = str(home_dir or "").strip()
+    if not value:
+        raise ValueError("Unable to resolve the current user home directory")
+    return value
+
+
+def resolve_portable_state_dir(platform, env=None, home_dir=None):
+    home_dir = Path.home() if home_dir is None else home_dir
+    if platform == "win32":
+        import ntpath
+        return ntpath.join(_require_home_directory(home_dir), ".tokensmind", "agent-network")
+    return os.path.join(_require_home_directory(home_dir), ".tokensmind", "agent-network")
+
+
+def _is_non_empty_string(value):
+    return isinstance(value, str) and bool(value)
+
+
+def _is_operation(value):
+    return (
+        isinstance(value, dict)
+        and value.get("method") in ("GET", "POST", "PATCH", "DELETE")
+        and _is_non_empty_string(value.get("path"))
+    )
+
+
+def _is_instance(value):
+    return isinstance(value, dict) and bool(UUID_PATTERN.match(str(value.get("id", ""))))
+
+
+def _is_active(value):
+    if not isinstance(value, dict):
+        return False
+    token = value.get("token", "")
+    prefix = value.get("tokenPrefix", "")
+    return (
+        bool(AGENT_TOKEN_PATTERN.match(token))
+        and (value.get("agentId") is None or _is_non_empty_string(value.get("agentId")))
+        and _is_non_empty_string(value.get("credentialId"))
+        and _is_non_empty_string(prefix)
+        and token.startswith(prefix)
+    )
+
+
+def _has_pending_secrets(value):
+    token = value.get("token", "")
+    prefix = value.get("tokenPrefix", "")
+    return (
+        bool(UUID_PATTERN.match(str(value.get("authorizationId", ""))))
+        and bool(UUID_PATTERN.match(str(value.get("instanceId", ""))))
+        and bool(UUID_PATTERN.match(str(value.get("createIdempotencyKey", ""))))
+        and bool(UUID_PATTERN.match(str(value.get("exchangeIdempotencyKey", ""))))
+        and bool(DEVICE_CODE_PATTERN.match(value.get("deviceCode", "")))
+        and bool(SHA256_PATTERN.match(value.get("deviceCodeHash", "")))
+        and bool(AGENT_TOKEN_PATTERN.match(token))
+        and bool(SHA256_PATTERN.match(value.get("tokenHash", "")))
+        and _is_non_empty_string(prefix)
+        and token.startswith(prefix)
+    )
+
+
+def parse_datetime_millis(value):
+    if not isinstance(value, str):
+        raise ValueError("Invalid Agent Network timestamp")
+    normalized = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        return int(datetime.fromisoformat(normalized).timestamp() * 1000)
+    except ValueError as error:
+        raise ValueError("Invalid Agent Network timestamp") from error
+
+
+def _has_authorization(value):
+    authorization = value.get("authorization")
+    if not isinstance(authorization, dict):
+        return False
+    interval = authorization.get("intervalSeconds")
+    try:
+        parse_datetime_millis(authorization.get("expiresAt"))
+    except ValueError:
+        return False
+    return (
+        authorization.get("authorizationId") == value.get("authorizationId")
+        and _is_non_empty_string(authorization.get("verificationUrl"))
+        and isinstance(interval, int) and not isinstance(interval, bool) and interval > 0
+    )
+
+
+def _is_pending(value):
+    if not isinstance(value, dict) or value.get("phase") not in PENDING_PHASES:
+        return False
+    if not _is_operation(value.get("operation")) or not _has_pending_secrets(value):
+        return False
+    return value["phase"] == "prepared" or _has_authorization(value)
+
+
+def _validate_record(name, value):
+    valid = _is_active(value) if name == "active" else _is_pending(value)
+    if name == "instance":
+        valid = _is_instance(value)
+    if not valid:
+        raise ValueError("Portable Agent Network %s state has an invalid structure" % name)
+
+
+def _validate_record_name(name):
+    if name not in RECORD_NAMES:
+        raise ValueError("Unsupported portable state record: %s" % name)
+
+
+def _origin_namespace(origin):
+    parsed = urlsplit(origin)
+    normalized = "%s://%s" % (parsed.scheme, parsed.netloc)
+    if parsed.scheme not in ("http", "https") or normalized != origin:
+        raise ValueError("Portable Agent Network store requires a normalized HTTP origin")
+    return sha256(origin.encode("utf-8")).hexdigest()
+
+
+class PortableStore:
+    def __init__(self, origin, platform, state_dir=None, *, env=None, home_dir=None):
+        base = state_dir or resolve_portable_state_dir(platform, env, home_dir)
+        self._directory = os.path.join(os.path.abspath(str(base)), _origin_namespace(origin))
+        self._platform = platform
+
+    def _record_path(self, name):
+        return os.path.join(self._directory, "%s.json" % name)
+
+    def read(self, name):
+        _validate_record_name(name)
+        try:
+            with open(self._record_path(name), "r", encoding="utf-8") as source:
+                value = json.load(source)
+        except FileNotFoundError:
+            return None
+        except json.JSONDecodeError as error:
+            raise ValueError("Portable Agent Network %s state is invalid JSON" % name) from error
+        _validate_record(name, value)
+        return value
+
+    def write(self, name, value):
+        _validate_record_name(name)
+        _validate_record(name, value)
+        os.makedirs(self._directory, mode=DIRECTORY_MODE, exist_ok=True)
+        if self._platform != "win32":
+            os.chmod(self._directory, DIRECTORY_MODE)
+        temporary = self._write_temporary(name, value)
+        try:
+            os.replace(temporary, self._record_path(name))
+            if self._platform != "win32":
+                os.chmod(self._record_path(name), FILE_MODE)
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+
+    def _write_temporary(self, name, value):
+        descriptor, temporary = tempfile.mkstemp(
+            prefix=".%s.%s." % (name, os.getpid()), suffix=".tmp", dir=self._directory,
+        )
+        try:
+            if self._platform != "win32":
+                os.fchmod(descriptor, FILE_MODE)
+            with os.fdopen(descriptor, "w", encoding="utf-8") as target:
+                json.dump(value, target, separators=(",", ":"))
+                target.flush()
+                os.fsync(target.fileno())
+            return temporary
+        except Exception:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+            raise
+
+    def remove(self, name):
+        _validate_record_name(name)
+        try:
+            os.unlink(self._record_path(name))
+        except FileNotFoundError:
+            return

package/skills/tokensmind-agent-network-runtime/scripts/python_runtime/request_policy.py

@@ -0,0 +1,85 @@
+from urllib.parse import parse_qsl, urljoin, urlsplit, urlunsplit
+
+from .constants import INTERNAL_PATH_PATTERNS, MUTATION_METHODS, SUPPORTED_METHODS
+
+PUBLIC_AGENT_DIRECTORY_PATH = "/agent-network-api/agents"
+
+
+def normalize_base_url(value):
+    parsed = urlsplit(str(value))
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        raise ValueError("Agent Network baseUrl must use http or https")
+    if parsed.username or parsed.password:
+        raise ValueError("Agent Network baseUrl must not contain credentials")
+    host = parsed.hostname.lower()
+    if ":" in host:
+        host = "[%s]" % host
+    port = parsed.port
+    default_port = 80 if parsed.scheme == "http" else 443
+    authority = host if port in (None, default_port) else "%s:%s" % (host, port)
+    return urlunsplit((parsed.scheme.lower(), authority, "", "", ""))
+
+
+def _is_internal_path(path):
+    return any(pattern.search(path) for pattern in INTERNAL_PATH_PATTERNS)
+
+
+def _validated_method(request):
+    method = str(request.get("method", "undefined")).upper()
+    if method not in SUPPORTED_METHODS:
+        raise ValueError("Unsupported Agent Network method: %s" % method)
+    return method
+
+
+def _validated_path(request):
+    path = request.get("path")
+    if not isinstance(path, str) or not path.startswith("/agent-network-api/"):
+        raise ValueError("Agent Network path must start with /agent-network-api/")
+    if _is_internal_path(path):
+        raise ValueError("This endpoint is not available through the ordinary-user connector")
+    return path
+
+
+def _validated_key(request, method):
+    key = request.get("idempotencyKey")
+    normalized_key = key.strip() if isinstance(key, str) else None
+    if method in MUTATION_METHODS and not normalized_key:
+        raise ValueError("Mutating Agent Network requests require a stable Idempotency-Key")
+    return normalized_key
+
+
+def _validate_reauthorize(request):
+    reauthorize = request.get("reauthorize")
+    if "reauthorize" in request and not isinstance(reauthorize, bool):
+        raise ValueError("Agent Network reauthorize must be a boolean")
+
+
+def validate_business_request(request):
+    method = _validated_method(request)
+    path = _validated_path(request)
+    normalized_key = _validated_key(request, method)
+    _validate_reauthorize(request)
+    operation = {"method": method, "path": path}
+    if normalized_key:
+        operation["idempotencyKey"] = normalized_key
+    return operation
+
+
+def build_business_url(base_url, path):
+    url = urljoin(base_url + "/", path)
+    parsed = urlsplit(url)
+    origin = normalize_base_url(url)
+    if origin != base_url or not parsed.path.startswith("/agent-network-api/"):
+        raise ValueError("Agent Network request must remain on the configured origin")
+    if _is_internal_path(parsed.path):
+        raise ValueError("This endpoint is not available through the ordinary-user connector")
+    return url
+
+
+def is_public_discovery_request(operation):
+    if operation.get("method") != "GET":
+        return False
+    parsed = urlsplit(operation.get("path", ""))
+    query = parse_qsl(parsed.query)
+    mine_requested = any(key == "mine" and value == "1" for key, value in query)
+    return parsed.path == PUBLIC_AGENT_DIRECTORY_PATH and not mine_requested

package/skills/tokensmind-agent-network-runtime/scripts/python_runtime/system_credential_store.py

@@ -0,0 +1,143 @@
+import json
+import os
+import shutil
+import subprocess
+
+from .portable_store import RECORD_NAMES, _validate_record
+
+SERVICE_NAME = "TokensMind Agent Network"
+APPLICATION_NAME = "tokensmind-agent-network"
+MACOS_SECURITY_PATH = "/usr/bin/security"
+MACOS_ITEM_NOT_FOUND = 44
+
+
+def _validate_record_name(name):
+    if name not in RECORD_NAMES:
+        raise ValueError("Unsupported portable state record: %s" % name)
+
+
+def _parse_record(name, source):
+    try:
+        value = json.loads(source)
+    except json.JSONDecodeError as error:
+        raise ValueError(
+            "System Agent Network %s credential is invalid JSON" % name,
+        ) from error
+    _validate_record(name, value)
+    return value
+
+
+def _command_failure(backend, operation, result):
+    return RuntimeError(
+        "%s %s failed with exit code %s" % (backend, operation, result.returncode),
+    )
+
+
+def run_credential_command(args, input_text=""):
+    return subprocess.run(
+        args,
+        input=input_text,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+
+
+class MacOSCredentialStore:
+    def __init__(self, namespace, runner=run_credential_command):
+        self._namespace = namespace
+        self._runner = runner
+
+    def _account(self, name):
+        _validate_record_name(name)
+        return "%s:%s" % (self._namespace, name)
+
+    def read(self, name):
+        result = self._runner([
+            MACOS_SECURITY_PATH, "find-generic-password",
+            "-a", self._account(name), "-s", SERVICE_NAME, "-w",
+        ])
+        if result.returncode == MACOS_ITEM_NOT_FOUND:
+            return None
+        if result.returncode != 0:
+            raise _command_failure("macOS Keychain", "read", result)
+        return _parse_record(name, result.stdout.strip())
+
+    def write(self, name, value):
+        _validate_record(name, value)
+        result = self._runner([
+            MACOS_SECURITY_PATH, "add-generic-password",
+            "-a", self._account(name), "-s", SERVICE_NAME, "-U", "-w",
+        ], json.dumps(value, separators=(",", ":")) + "\n")
+        if result.returncode != 0:
+            raise _command_failure("macOS Keychain", "write", result)
+
+    def remove(self, name):
+        result = self._runner([
+            MACOS_SECURITY_PATH, "delete-generic-password",
+            "-a", self._account(name), "-s", SERVICE_NAME,
+        ])
+        if result.returncode not in (0, MACOS_ITEM_NOT_FOUND):
+            raise _command_failure("macOS Keychain", "remove", result)
+
+
+class LinuxSecretServiceStore:
+    def __init__(self, namespace, command, runner=run_credential_command):
+        self._namespace = namespace
+        self._command = command
+        self._runner = runner
+
+    def _attributes(self, name):
+        _validate_record_name(name)
+        return [
+            "application", APPLICATION_NAME,
+            "origin", self._namespace,
+            "record", name,
+        ]
+
+    def read(self, name):
+        result = self._runner([self._command, "lookup"] + self._attributes(name))
+        missing = (
+            result.returncode == 1
+            and not result.stdout.strip()
+            and not result.stderr.strip()
+        )
+        if missing:
+            return None
+        if result.returncode != 0:
+            raise _command_failure("Linux Secret Service", "read", result)
+        return _parse_record(name, result.stdout.strip())
+
+    def write(self, name, value):
+        _validate_record(name, value)
+        result = self._runner(
+            [self._command, "store", "--label=%s" % SERVICE_NAME]
+            + self._attributes(name),
+            json.dumps(value, separators=(",", ":")) + "\n",
+        )
+        if result.returncode != 0:
+            raise _command_failure("Linux Secret Service", "write", result)
+
+    def remove(self, name):
+        if self.read(name) is None:
+            return
+        result = self._runner([self._command, "clear"] + self._attributes(name))
+        if result.returncode != 0:
+            raise _command_failure("Linux Secret Service", "remove", result)
+
+
+def resolve_system_credential_store(
+        platform, namespace, env=None, *, runner=run_credential_command):
+    if platform == "darwin":
+        if not os.path.isfile(MACOS_SECURITY_PATH):
+            return None
+        if not os.access(MACOS_SECURITY_PATH, os.X_OK):
+            return None
+        return MacOSCredentialStore(namespace, runner)
+    if platform == "linux":
+        environment = os.environ if env is None else env
+        command = shutil.which("secret-tool", path=environment.get("PATH"))
+        if command:
+            return LinuxSecretServiceStore(namespace, command, runner)
+    return None

package/src/action-context.js

@@ -0,0 +1,23 @@
+function mutationKey(workflow, label) {
+  return `${workflow.id}:${label}`;
+}
+
+export function createActionContext({ api, workflow }) {
+  return {
+    input: workflow.input,
+    get(path) {
+      return api.request({ method: 'GET', path });
+    },
+    mutate({ method, path, body, label }) {
+      return api.request({
+        method,
+        path,
+        body,
+        idempotencyKey: mutationKey(workflow, label),
+      });
+    },
+    messageId(label) {
+      return mutationKey(workflow, `${label}:message`);
+    },
+  };
+}

package/src/action-errors.js

@@ -0,0 +1,55 @@
+export class ActionState extends Error {
+  constructor(status, data) {
+    super(data?.message || status);
+    this.name = 'ActionState';
+    this.status = status;
+    this.data = data || {};
+  }
+}
+
+export class ActionFailure extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'ActionFailure';
+    this.code = code;
+    this.details = details;
+    this.retryable = false;
+  }
+}
+
+export function requireInput(fields, message = 'Agent Network action needs more input.') {
+  throw new ActionState('input_required', { fields, message });
+}
+
+export function requireSelection(candidates, message) {
+  throw new ActionState('selection_required', { candidates, message });
+}
+
+export function actionFailure(code, message, details) {
+  throw new ActionFailure(code, message, details);
+}
+
+function isRetryable(error) {
+  if (error?.retryable === true) return true;
+  if (error?.status === 429) return true;
+  if (Number(error?.status) >= 500) return true;
+  return error?.code === 'AGENT_NETWORK_TRANSPORT_ERROR';
+}
+
+function optionalFailureFields(error) {
+  const fields = {};
+  if (Number.isInteger(error?.status)) fields.httpStatus = error.status;
+  if (error?.correction) fields.correction = error.correction;
+  if (error?.retryAfter) fields.retryAfter = error.retryAfter;
+  if (error?.details) fields.details = error.details;
+  return fields;
+}
+
+export function serializeFailure(error) {
+  return {
+    code: error?.code || 'AGENT_NETWORK_ACTION_ERROR',
+    message: error instanceof Error ? error.message : String(error),
+    retryable: isRetryable(error),
+    ...optionalFailureFields(error),
+  };
+}

package/src/action-executor.js

@@ -0,0 +1,126 @@
+import { randomUUID } from 'node:crypto';
+import { ActionState, serializeFailure } from './action-errors.js';
+import { createActionContext } from './action-context.js';
+import { validateActionRequest } from './action-validation.js';
+import { ensureAgent, getMyAgent, searchAgents } from './agent-actions.js';
+import { contactAgent } from './contact-action.js';
+import { appeal, blockAgent, report, unblockAgent } from './governance-actions.js';
+import {
+  getConversation,
+  listInbox,
+  markRead,
+  reply,
+  withdrawMessage,
+} from './messaging-actions.js';
+
+const ACTIONS = Object.freeze({
+  appeal,
+  block_agent: blockAgent,
+  contact_agent: contactAgent,
+  ensure_agent: ensureAgent,
+  get_conversation: getConversation,
+  get_my_agent: getMyAgent,
+  list_inbox: listInbox,
+  mark_read: markRead,
+  reply,
+  report,
+  search_agents: searchAgents,
+  unblock_agent: unblockAgent,
+  withdraw_message: withdrawMessage,
+});
+
+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 requestsMatch(workflow, request) {
+  return JSON.stringify(canonicalize({
+    operation: workflow.operation,
+    input: workflow.input,
+  })) === JSON.stringify(canonicalize(request));
+}
+
+async function loadWorkflow({ request, store, randomId }) {
+  let current = await store.read('workflow');
+  if (!current) {
+    const candidate = { version: 1, id: randomId(), ...request };
+    await store.write('workflow', candidate);
+    current = await store.read('workflow');
+  }
+  if (!current) throw new Error('Workflow claim returned no state');
+  if (current && !requestsMatch(current, request)) {
+    const error = new Error(`Another ${current.operation} action is pending.`);
+    error.code = 'AGENT_NETWORK_ACTION_PENDING';
+    throw error;
+  }
+  return current;
+}
+
+async function handleFailure(error, store) {
+  if (error instanceof ActionState) {
+    if (error.status !== 'authorization_required') await store.remove('workflow');
+    return { status: error.status, ...error.data };
+  }
+  if (error?.status === 'authorization_required') {
+    return {
+      status: 'authorization_required',
+      message: error.message,
+      verificationUrl: error.verificationUrl,
+    };
+  }
+  const serialized = serializeFailure(error);
+  if (!serialized.retryable) await store.remove('workflow');
+  return { status: 'failed', ...serialized };
+}
+
+function serializeWithoutCleanup(error) {
+  if (error instanceof ActionState) return { status: error.status, ...error.data };
+  return { status: 'failed', ...serializeFailure(error) };
+}
+
+async function abandonWorkflow(store) {
+  const abandoned = await store.remove('workflow');
+  return {
+    status: 'completed',
+    operation: 'abandon_action',
+    data: { abandoned },
+  };
+}
+
+export function createActionExecutor({ api, workflowStore, randomId = randomUUID }) {
+  return {
+    async execute(value) {
+      let request;
+      try {
+        request = validateActionRequest(value);
+      } catch (error) {
+        return serializeWithoutCleanup(error);
+      }
+      if (request.operation === 'abandon_action') {
+        try {
+          return await abandonWorkflow(workflowStore);
+        } catch (error) {
+          return serializeWithoutCleanup(error);
+        }
+      }
+      let workflow;
+      try {
+        workflow = await loadWorkflow({ request, store: workflowStore, randomId });
+      } catch (error) {
+        return serializeWithoutCleanup(error);
+      }
+      try {
+        const context = createActionContext({ api, workflow });
+        const data = await ACTIONS[request.operation](context);
+        await workflowStore.remove('workflow');
+        return { status: 'completed', operation: request.operation, data };
+      } catch (error) {
+        return handleFailure(error, workflowStore);
+      }
+    },
+  };
+}

package/src/action-validation.js

@@ -0,0 +1,61 @@
+import { requireInput } from './action-errors.js';
+
+export const OPERATIONS = Object.freeze([
+  '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',
+]);
+
+const OPERATION_SET = new Set(OPERATIONS);
+
+export function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function requiredText(input, field) {
+  const value = text(input?.[field]);
+  if (!value) requireInput([field]);
+  return value;
+}
+
+export function requiredId(input, field) {
+  return requiredText(input, field);
+}
+
+export function optionalLimit(value, fallback = 20) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number <= 0 || number > 100) {
+    requireInput(['limit'], 'limit must be an integer from 1 to 100.');
+  }
+  return number;
+}
+
+export function validateActionRequest(value) {
+  if (!isObject(value)) requireInput(['operation', 'input']);
+  const unexpected = Object.keys(value).filter((key) => !['operation', 'input'].includes(key));
+  if (unexpected.length) {
+    requireInput(['operation', 'input'], `Unsupported top-level fields: ${unexpected.join(', ')}`);
+  }
+  const operation = text(value.operation);
+  if (!OPERATION_SET.has(operation)) {
+    requireInput(['operation'], `Unsupported Agent Network operation: ${operation || '(empty)'}`);
+  }
+  if (value.input !== undefined && !isObject(value.input)) requireInput(['input']);
+  return { operation, input: value.input || {} };
+}