Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.
JavaScript agent-collaborationagent-harnessagent-orchestrationagent-teamagent-workflowai-assistantai-automationai-employeeai-productivityai-teamai-workflowautonomous-agentsclaude-code-guiclaude-coworkdesktop-agentlocal-firstmulti-agentmulti-agent-systemself-evolving-agentstask-automation
#!/usr/bin/env node
'use strict';
/** Governed MCP facade over official provider CLIs.
*
* The facade deliberately exposes six stable tools rather than a raw command runner. Every
* action must belong to a reviewed business domain, is classified against provider schema/help,
* and can only pass through the matching read/write/high-impact/destructive tool.
*/
const { spawn } = require('node:child_process');
const { killProcessTree } = require('./bridge-skill-runner.cjs');
const fs = require('node:fs');
const path = require('node:path');
const os = require('node:os');
const larkContract = require('./local-cli-lark.cjs');
const permissions = require('./local-cli-permissions.cjs');
const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
const MANIFESTS = Object.freeze({
wecom: Object.freeze({
package: '@wecom/[email protected]',
integrity: 'sha512-GaVCie2We3EWrOiIYlXp5FpjznikbS1oShFyZjIz2uDDdQlkbA8CJzjhzrAzRgIDU/oaxpmEucp9WHN/yiuzuQ==',
executable: 'wecom-cli',
domains: Object.freeze([
'calendar', 'chat', 'contact', 'disk', 'doc', 'identity', 'mail', 'media', 'message',
'meeting', 'sheet', 'smartpage', 'smartsheet', 'todo',
]),
status: () => ['auth', 'show', '--status'],
}),
lark: Object.freeze({
package: '@larksuite/[email protected]',
integrity: 'sha512-QARcHz96pfEzzRZdjXene5h9fJ46lCu5q2TWx+blLyOIXEPuJwi6bT+RT9hPOsKFW+bbGYvamU8LpD6FsIa5ew==',
executable: 'lark-cli',
domains: Object.freeze([
'approval', 'attendance', 'base', 'calendar', 'contact', 'docs', 'drive', 'im',
'mail', 'markdown', 'mindnotes', 'minutes', 'note', 'okr', 'sheets', 'slides',
'task', 'vc', 'wiki',
]),
status: (env) => ['auth', 'status', '--profile', env.ORKAS_LOCAL_CLI_PROFILE],
}),
dingtalk: Object.freeze({
package: '[email protected]',
integrity: 'sha512-lYLLqE3jDRqzf3ekjaOnBqD222fsbRkEiO4GsR6k8aMiybEUTQDr7BC9/4Wtm2KeL+PiukBqfZ9EFULS22jdBA==',
executable: 'dws',
domains: Object.freeze([
'agoal', 'aisearch', 'aitable', 'attendance', 'calendar', 'chat', 'contact', 'ding',
'doc', 'drive', 'hrbrain', 'live', 'mail', 'minutes', 'oa', 'recruit', 'report',
'sheet', 'todo', 'whiteboard', 'wiki',
]),
status: () => ['auth', 'status', '--format', 'json'],
}),
xero: Object.freeze({
package: '@xeroapi/[email protected]',
integrity: 'sha512-H0GITjyzP7Zek/6zinvpOjY/Ed7nyf21c9n+hzi81lTFrRp/foMRwL6Gx7IktsOyeo0DSJ4Y/y6VqNrwyiodEA==',
executable: 'xero',
domains: Object.freeze([
'accounts', 'bank-transactions', 'contact-groups', 'contacts', 'credit-notes',
'currencies', 'invoices', 'items', 'manual-journals', 'org', 'payments', 'quotes',
'reports', 'tax-rates', 'tracking',
]),
status: (env) => ['org', 'details', '--profile', env.ORKAS_LOCAL_CLI_PROFILE, '--json'],
}),
});
const TOOL_POLICIES = Object.freeze({
list_capabilities: Object.freeze({ risk: 'R', confirmation: 'none', maxBatchSize: 100 }),
describe_action: Object.freeze({ risk: 'R', confirmation: 'none', maxBatchSize: 1 }),
execute_read: Object.freeze({ risk: 'R', confirmation: 'none', maxBatchSize: 100 }),
execute_write: Object.freeze({ risk: 'W', confirmation: 'preview', maxBatchSize: 25 }),
execute_high_impact: Object.freeze({ risk: 'H', confirmation: 'fresh', maxBatchSize: 10, sensitiveOperation: 'external_or_workflow_change' }),
execute_destructive: Object.freeze({ risk: 'D', confirmation: 'destructive', maxBatchSize: 10, sensitiveOperation: 'destructive' }),
});
const ACTION_SCHEMA = Object.freeze({
type: 'object',
properties: {
action: {
type: 'string',
description: 'Canonical provider action, for example calendar.events.list or todo task create. Call describe_action first.',
},
parameters: {
type: 'object',
description: 'Named parameters from describe_action. Local file inputs require absolute paths in Orkas-approved roots; raw CLI flags and output paths are rejected.',
additionalProperties: true,
},
},
required: ['action'],
additionalProperties: false,
});
function tool(name, description, inputSchema, annotations) {
const policy = TOOL_POLICIES[name];
return {
name,
description,
inputSchema,
annotations,
_meta: { orkas: { actionPolicy: policy } },
};
}
const TOOLS = Object.freeze([
tool('list_capabilities', 'List reviewed business domains, or progressively inspect the official schema under one returned domain or subgroup path.', {
type: 'object',
properties: {
path: {
type: 'string',
description: 'Optional canonical domain or subgroup path returned by an earlier capability result.',
},
},
additionalProperties: false,
}, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }),
tool('describe_action', 'Inspect the official schema/help and Orkas risk classification for one action before executing it.', {
type: 'object', properties: { action: { type: 'string' } }, required: ['action'], additionalProperties: false,
}, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }),
tool('execute_read', 'Execute a schema-verified read-only action.', ACTION_SCHEMA, {
readOnlyHint: true, destructiveHint: false, openWorldHint: true,
}),
tool('execute_write', 'Execute a normal create/update action after preview confirmation.', ACTION_SCHEMA, {
readOnlyHint: false, destructiveHint: false, openWorldHint: true,
}),
tool('execute_high_impact', 'Execute an externally visible communication, approval, sharing, publishing, or workflow action after fresh confirmation.', ACTION_SCHEMA, {
readOnlyHint: false, destructiveHint: false, openWorldHint: true,
}),
tool('execute_destructive', 'Execute a delete/cancel/remove/revoke/withdraw action after destructive confirmation.', ACTION_SCHEMA, {
readOnlyHint: false, destructiveHint: true, openWorldHint: true,
}),
]);
const BLOCKED_ROOTS = new Set([
'api', 'auth', 'config', 'doctor', 'event', 'extension', 'help', 'install', 'mcp',
'openapi', 'plugin', 'profile', 'schema', 'skill', 'update', 'upgrade', 'version',
'devapp', 'devdoc', 'pat',
]);
const BLOCKED_PARAMETER_KEYS = /^(?:app[_-]?secret|client[_-]?secret|access[_-]?token|refresh[_-]?token|authorization|config|profile|cwd|directory|dir|output|output[_-]?(?:dir|file|path)|yes|dry[_-]?run)$/i;
const CREDENTIAL_PARAMETER_KEYS = /^(?:app[_-]?secret|client[_-]?secret|access[_-]?token|refresh[_-]?token|id[_-]?token|authorization|api[_-]?key|password|cookie)$/i;
const LOCAL_INPUT_PARAMETER_KEYS = /^(?:file|file[_-]?path|input[_-]?file)$/i;
const DESTRUCTIVE_VERBS = new Set(['cancel', 'clear', 'delete', 'destroy', 'dismiss', 'purge', 'remove', 'reset', 'revoke', 'terminate', 'withdraw']);
const HIGH_IMPACT_VERBS = new Set(['approve', 'assign', 'broadcast', 'forward', 'invite', 'pay', 'publish', 'reject', 'reply', 'refund', 'send', 'share', 'submit', 'transfer']);
const WRITE_VERBS = new Set(['add', 'append', 'archive', 'complete', 'copy', 'create', 'edit', 'import', 'mark', 'move', 'patch', 'restore', 'set', 'start', 'stop', 'update', 'upload']);
const READ_VERBS = new Set(['check', 'count', 'download', 'export', 'find', 'get', 'info', 'instance_view', 'list', 'query', 'read', 'search', 'show', 'status', 'view']);
const MAX_OUTPUT_CHARS = 1024 * 1024;
const MAX_INPUT_CHARS = 256 * 1024;
const MAX_XERO_INPUT_FILE_BYTES = 8 * 1024 * 1024;
const XERO_READ_ACTIONS = new Set([
'accounts.list', 'bank-transactions.list', 'contact-groups.list', 'contacts.list',
'credit-notes.list', 'currencies.list', 'invoices.list', 'items.list',
'manual-journals.list', 'org.details', 'payments.list', 'quotes.list',
'reports.aged-payables', 'reports.aged-receivables', 'reports.balance-sheet',
'reports.profit-and-loss', 'reports.trial-balance', 'tax-rates.list',
'tracking.categories.list',
]);
const XERO_HIGH_IMPACT_ROOTS = new Set([
'bank-transactions', 'credit-notes', 'invoices', 'manual-journals', 'payments', 'quotes',
]);
function configuredManifest(env = process.env) {
const provider = String(env.ORKAS_LOCAL_CLI_PROVIDER || '');
const manifest = MANIFESTS[provider];
if (!manifest) throw new Error('unsupported local CLI provider');
if (env.ORKAS_LOCAL_CLI_PACKAGE !== manifest.package) throw new Error('local CLI package pin mismatch');
if (env.ORKAS_LOCAL_CLI_PACKAGE_INTEGRITY !== manifest.integrity) throw new Error('local CLI package integrity mismatch');
if (env.ORKAS_LOCAL_CLI_EXECUTABLE !== manifest.executable) throw new Error('local CLI executable mismatch');
let configuredDomains;
try { configuredDomains = JSON.parse(env.ORKAS_LOCAL_CLI_ALLOWED_DOMAINS_JSON || '[]'); }
catch { configuredDomains = []; }
if (JSON.stringify(configuredDomains) !== JSON.stringify(manifest.domains)) {
throw new Error('local CLI domain policy mismatch');
}
if (!env.ORKAS_NODE || !env.ORKAS_LOCAL_CLI_NPX_CLI || !env.ORKAS_LOCAL_CLI_RUNTIME_DIR
|| path.resolve(String(env.ORKAS_LOCAL_CLI_WORK_DIR || '')) !== path.join(env.ORKAS_LOCAL_CLI_RUNTIME_DIR, 'work')) {
throw new Error('local CLI runtime is incomplete');
}
return { provider, ...manifest };
}
function assertPackageIntegrityMarker(manifest, env = process.env) {
const marker = String(env.ORKAS_LOCAL_CLI_INTEGRITY_MARKER || '');
const runtimeDir = String(env.ORKAS_LOCAL_CLI_RUNTIME_DIR || '');
if (!marker || path.dirname(marker) !== runtimeDir) throw new Error('local CLI integrity marker is unavailable; reconnect this connector');
let recorded;
try { recorded = JSON.parse(fs.readFileSync(marker, 'utf8')); }
catch { throw new Error('local CLI package integrity is unverified; reconnect this connector'); }
if (recorded?.package !== manifest.package || recorded?.integrity !== manifest.integrity) {
throw new Error('local CLI package integrity pin changed; reconnect this connector');
}
}
function actionTokens(value) {
const action = String(value || '').trim();
if (!action || action.length > 240 || action.startsWith('-') || !/^[A-Za-z0-9_+.-]+(?:[ .][A-Za-z0-9_+.-]+)*$/.test(action)) {
throw new Error('invalid action; use the canonical action returned by describe_action');
}
const tokens = action.split(/[. ]+/).filter(Boolean);
if (tokens.length < 2 || tokens.length > 12) throw new Error('action must include a domain and operation');
return tokens;
}
function capabilityTokens(value) {
const candidate = String(value || '').trim();
if (!candidate || candidate.length > 240 || candidate.startsWith('-') || !/^[A-Za-z0-9_+.-]+(?:[ .][A-Za-z0-9_+.-]+)*$/.test(candidate)) {
throw new Error('invalid capability path; use a domain or subgroup returned by list_capabilities');
}
const tokens = candidate.split(/[. ]+/).filter(Boolean);
if (tokens.length < 1 || tokens.length > 11) throw new Error('capability path is too deep');
return tokens;
}
function validateCapabilityPath(value, env = process.env) {
const manifest = configuredManifest(env);
const tokens = capabilityTokens(value);
if (tokens.some((token) => token.startsWith('-'))) throw new Error('raw CLI flags are not allowed in capability path');
const root = tokens[0].toLowerCase();
if (BLOCKED_ROOTS.has(root) || !manifest.domains.includes(root)) {
throw new Error(`capability domain is not allowed: ${root}`);
}
return { manifest, tokens, canonical: tokens.join('.'), cliPath: tokens.join(' ') };
}
function validateAction(action, env = process.env) {
const manifest = configuredManifest(env);
const tokens = actionTokens(action);
const root = tokens[0].toLowerCase();
if (BLOCKED_ROOTS.has(root) || !manifest.domains.includes(root)) {
throw new Error(`action domain is not allowed: ${root}`);
}
if (tokens.some((token) => token.startsWith('-'))) throw new Error('raw CLI flags are not allowed in action');
return { manifest, tokens, canonical: tokens.join('.'), cliPath: tokens.join(' ') };
}
function riskFromMetadata(value) {
const seen = new Set();
const risks = new Set();
function visit(node) {
if (!node || typeof node !== 'object' || seen.has(node)) return;
seen.add(node);
for (const [childKey, child] of Object.entries(node)) {
const normalizedKey = String(childKey).toLowerCase();
if (/^(?:risk|effect|confirmation|side_effect|operation_type)$/.test(normalizedKey)) {
const text = String(child).toLowerCase();
if (/destructive|delete|danger/.test(text)) risks.add('D');
else if (/high|sensitive|external/.test(text)) risks.add('H');
else if (/write|mutat|create|update|medium/.test(text)) risks.add('W');
else if (/read|none|safe|low/.test(text)) risks.add('R');
}
visit(child);
}
}
visit(value);
return ['D', 'H', 'W', 'R'].find((risk) => risks.has(risk)) || '';
}
function classifyAction(action, schema) {
const metadataRisk = riskFromMetadata(schema);
const tokens = actionTokens(action).flatMap((token) => token
.replace(/^\+/, '')
.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
.toLowerCase()
.split(/[_+-]+/)
.filter(Boolean));
let actionRisk = '';
for (const token of tokens) if (DESTRUCTIVE_VERBS.has(token)) actionRisk = 'D';
if (!actionRisk) for (const token of tokens) if (HIGH_IMPACT_VERBS.has(token)) actionRisk = 'H';
if (!actionRisk) for (const token of tokens) if (WRITE_VERBS.has(token)) actionRisk = 'W';
for (let index = tokens.length - 1; index >= 1; index--) {
const token = tokens[index];
if (!actionRisk && (READ_VERBS.has(token) || /^(?:list|get|read|search|find|query|show|check|view)/.test(token))) {
actionRisk = 'R';
}
}
if (metadataRisk && actionRisk) {
const rank = { R: 1, W: 2, H: 3, D: 4 };
return rank[metadataRisk] >= rank[actionRisk] ? metadataRisk : actionRisk;
}
if (metadataRisk || actionRisk) return metadataRisk || actionRisk;
// Unknown verbs fail into the confirmation-heavy lane rather than being mistaken for reads.
return 'H';
}
function classifyXeroAction(action) {
const canonical = actionTokens(action).join('.').toLowerCase();
if (XERO_READ_ACTIONS.has(canonical)) return 'R';
const tokens = canonical.split('.');
if (XERO_HIGH_IMPACT_ROOTS.has(tokens[0]) && ['create', 'update'].includes(tokens.at(-1))) return 'H';
if (['create', 'update'].includes(tokens.at(-1))) return 'W';
return 'H';
}
function containsDestructiveStatus(value, seen = new Set()) {
if (!value || typeof value !== 'object' || seen.has(value)) return false;
seen.add(value);
for (const [key, child] of Object.entries(value)) {
if (/status/i.test(key) && /^(?:archived|deleted|voided)$/i.test(String(child))) return true;
if (containsDestructiveStatus(child, seen)) return true;
}
return false;
}
function xeroInputHasDestructiveStatus(filePath) {
let failure = 'Xero input file could not be fully checked; use a readable UTF-8 JSON file with a simpler structure and try again';
const oversized = 'Xero input file exceeds 8 MiB; reduce the file size and try again';
try {
// Nonblocking open plus fstat rejects non-files without waiting on a FIFO.
const fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
try {
const stat = fs.fstatSync(fd);
if (!stat.isFile()) throw new Error();
if (stat.size > MAX_XERO_INPUT_FILE_BYTES) {
failure = oversized;
throw new Error();
}
// One extra byte detects overflow even if the file grew after fstat.
const bytes = Buffer.allocUnsafe(MAX_XERO_INPUT_FILE_BYTES + 1);
let length = 0;
while (length < bytes.length) {
const read = fs.readSync(fd, bytes, { offset: length, length: bytes.length - length, position: null });
if (read === 0) break;
length += read;
}
if (length > MAX_XERO_INPUT_FILE_BYTES) {
failure = oversized;
throw new Error();
}
const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
.decode(bytes.subarray(0, length));
return containsDestructiveStatus(JSON.parse(text));
} finally {
fs.closeSync(fd);
}
} catch {
// Do not expose filesystem paths, JSON excerpts or decoder errors.
throw new Error(failure);
}
}
function invocationRisk(baseRisk, parameters, env = process.env, inspection) {
const validated = validatedParameters(parameters, env, inspection);
if (env.ORKAS_LOCAL_CLI_PROVIDER === 'xero') {
let risk = containsDestructiveStatus(validated) ? 'D' : baseRisk;
for (const [key, value] of Object.entries(validated)) {
if (!LOCAL_INPUT_PARAMETER_KEYS.test(key)) continue;
// Check every file even when another parameter already requires D.
if (xeroInputHasDestructiveStatus(value)) risk = 'D';
}
return risk;
}
if (containsDestructiveStatus(validated)) return 'D';
for (const [key, value] of Object.entries(validated)) {
if (!LOCAL_INPUT_PARAMETER_KEYS.test(key) || typeof value !== 'string' || /^https:\/\//i.test(value)) continue;
try {
const stat = fs.statSync(value);
if (!stat.isFile() || stat.size > MAX_INPUT_CHARS) continue;
const payload = JSON.parse(fs.readFileSync(value, 'utf8'));
if (containsDestructiveStatus(payload)) return 'D';
} catch { /* The official CLI reports malformed or unreadable payloads after path validation. */ }
}
return baseRisk;
}
function allowedFileRoots(env) {
try {
const parsed = JSON.parse(env.ORKAS_LOCAL_CLI_ALLOWED_FILE_ROOTS_JSON || '[]');
return Array.isArray(parsed)
? parsed.filter((item) => typeof item === 'string' && path.isAbsolute(item)).map((item) => {
try { return fs.realpathSync(item); } catch { return path.resolve(item); }
})
: [];
} catch { return []; }
}
function isWithin(root, candidate) {
const relative = path.relative(root, candidate);
return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
}
// Normalize provider parameter contracts at one boundary. Neither action names
// nor path-looking literal values determine whether the CLI may read a file.
function parameterSchema(inspection) {
const schema = inspection?.schema || {};
if (inspection?.provider === 'wecom') return schema.schemas?.[schema.request?.$ref] || schema.request || {};
if (inspection?.provider === 'dingtalk') return { type: 'object', properties: schema.parameters || {} };
return schema.inputSchema || {};
}
function fileContract(property, provider) {
const description = typeof property?.description === 'string' ? property.description : '';
// Pinned Lark shortcut help is its official introspection format; API methods
// and WeCom expose binary markers, while DWS also exposes format/input facts.
const localPath = property?.format === 'binary' || property?.format === 'file-path'
|| property?.['x-wecom-octet-stream'] === true
|| (provider === 'lark' && (description.includes('cwd-relative local path') || description.startsWith('local file path')))
|| (provider === 'dingtalk' && description.startsWith('本地文件路径'));
const reference = (Array.isArray(property?.input) && property.input.includes('file')) || description.includes('supports @file')
|| (provider === 'dingtalk' && (property?.format === 'json' || description.includes('@file')));
return {
localPath, reference,
url: localPath && description.includes('URL'),
keyPrefixes: localPath ? ['file', 'img'].filter(prefix => description.includes(`${prefix}_xxx`)) : [],
};
}
function localInputs(value, env, inspection) {
const inputs = [];
const provider = env.ORKAS_LOCAL_CLI_PROVIDER;
const root = parameterSchema(inspection);
function visit(raw, property, keys) {
if (property?.$ref && provider === 'wecom') property = inspection?.schema?.schemas?.[property.$ref] || property;
const contract = fileContract(property, provider);
if (Array.isArray(raw)) {
if (property?.type === 'object') throw new Error('object parameter requires an object');
raw.forEach((item, index) => visit(item, { ...property, ...property?.items, type: property?.items?.type }, [...keys, index]));
return;
}
if (property?.type === 'object') {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('object parameter requires an object');
if (property.carrier === '--file') {
for (const field of property.required || []) {
if (!Object.hasOwn(raw, field)) throw new Error(`missing binary file field: ${field}`);
}
if (Object.keys(raw).some(field => property.properties?.[field]?.format !== 'binary')) {
throw new Error('unknown binary file field');
}
}
for (const [field, child] of Object.entries(raw)) visit(child, property.properties?.[field], [...keys, field]);
return;
}
if (contract.localPath) {
if (typeof raw === 'string' && ((contract.url && /^https:\/\//i.test(raw))
|| contract.keyPrefixes.some(prefix => new RegExp(`^${prefix}_[A-Za-z0-9_-]+$`).test(raw)))) return;
inputs.push({ keys, value: raw });
return;
}
if (typeof raw === 'string' && contract.reference) {
if (raw === '-' || raw === '@-') throw new Error('stdin input is not available through this connector');
if (raw.startsWith('@')) inputs.push({ keys, value: raw.slice(1), prefix: '@' });
return;
}
// DWS has legacy @file readers that are absent from some leaf contracts.
// Fail closed for their ASCII file-reference syntax; literal mentions stay text.
if (typeof raw === 'string' && provider === 'dingtalk' && /^@[A-Za-z0-9./~_-]/.test(raw)) {
throw new Error('indirect file input is not declared by this action; use inline content');
}
// Xero's existing full-JSON input inspection also serves callers that have
// no introspection result yet. Do not infer files from arbitrary strings.
if ((!inspection || provider === 'xero') && LOCAL_INPUT_PARAMETER_KEYS.test(String(keys.at(-1)))) {
if (typeof raw === 'string' && /^https:\/\//i.test(raw)) return;
inputs.push({ keys, value: raw });
}
}
for (const [key, raw] of Object.entries(value)) {
const property = root.properties?.[key] || root.properties?.[key.replace(/-/g, '_')]
|| root.properties?.[key.replace(/_/g, '-')];
visit(raw, property, [key]);
}
return inputs;
}
function approvedInputPath(input, env) {
if (typeof input !== 'string') throw new Error('local input parameter must be a path or HTTPS URL');
let candidate;
let stat;
try { candidate = fs.realpathSync(input); stat = fs.statSync(candidate); }
catch { throw new Error('local input file does not exist'); }
if (!path.isAbsolute(input) || !allowedFileRoots(env).some((root) => isWithin(root, candidate))) {
throw new Error('local input path is outside Orkas-approved roots');
}
if (env.ORKAS_LOCAL_CLI_PROVIDER !== 'xero' && !stat.isFile()) {
throw new Error('local input must be a regular file');
}
return candidate;
}
function validatedParameters(value, env = process.env, inspection) {
if (value == null) return {};
if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('parameters must be an object');
const serialized = JSON.stringify(value);
if (serialized.length > MAX_INPUT_CHARS) throw new Error('parameters are too large');
const seen = new Set();
function rejectNestedCredentials(node) {
if (!node || typeof node !== 'object' || seen.has(node)) return;
seen.add(node);
for (const [key, child] of Object.entries(node)) {
if (CREDENTIAL_PARAMETER_KEYS.test(key)) {
throw new Error(`credential parameter is not allowed: ${key}`);
}
rejectNestedCredentials(child);
}
}
rejectNestedCredentials(value);
const entries = Object.entries(value);
if (entries.length > 100) throw new Error('too many parameters');
const out = {};
for (const [key, raw] of entries) {
if (!/^[A-Za-z][A-Za-z0-9_.-]{0,79}$/.test(key) || BLOCKED_PARAMETER_KEYS.test(key)) {
throw new Error(`parameter is not allowed: ${key}`);
}
if (raw === undefined || typeof raw === 'function' || typeof raw === 'symbol') {
throw new Error(`invalid parameter value: ${key}`);
}
out[key] = raw;
}
for (const input of localInputs(out, env, inspection)) approvedInputPath(input.value, env);
return out;
}
async function prepareLocalInputs(parameters, inspection, env, signal) {
const inputs = localInputs(parameters, env, inspection);
// Xero reads absolute JSON input and owns full-payload destructive-state
// inspection. Do not replace that existing contract with a binary upload path.
if (!inputs.length || inspection.provider === 'xero') return { parameters, cleanup() {} };
// Provider config trees contain credentials. Lark rejects every upload from
// that tree, including runtime/work. Stage approved bytes in a private,
// per-call OS temporary directory and remove it on every terminal outcome.
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'orkas-cli-input-'));
const cleanup = () => fs.rmSync(directory, { recursive: true, force: true });
const prepared = structuredClone(parameters);
try {
for (const [index, input] of inputs.entries()) {
throwIfCancelled(signal);
const source = approvedInputPath(input.value, env);
const relative = path.join(String(index), path.basename(input.value));
const destination = path.join(directory, relative);
fs.mkdirSync(path.dirname(destination), { mode: 0o700 });
// Bound host staging; stricter media-specific limits belong to the provider.
const limit = input.prefix ? 8 * 1024 * 1024 : 5 * 1024 * 1024 * 1024;
const reader = await fs.promises.open(source, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | (fs.constants.O_NOFOLLOW || 0));
try {
const stat = await reader.stat();
if (!stat.isFile() || stat.size > limit) throw new Error('local input is not a regular file within the action size limit');
const current = fs.statSync(source);
if (approvedInputPath(source, env) !== source || current.dev !== stat.dev || current.ino !== stat.ino) {
throw new Error('local input changed while opening');
}
const writer = await fs.promises.open(destination, 'wx', 0o600);
try {
const buffer = Buffer.alloc(1024 * 1024);
let total = 0;
while (true) {
throwIfCancelled(signal);
const { bytesRead } = await reader.read(buffer, 0, buffer.length, null);
if (!bytesRead) break;
total += bytesRead;
if (total > limit) throw new Error('local input exceeds the action size limit');
let offset = 0;
while (offset < bytesRead) {
const { bytesWritten } = await writer.write(buffer, offset, bytesRead - offset, null);
if (!bytesWritten) throw new Error('local input staging failed');
offset += bytesWritten;
}
}
const after = await reader.stat();
if (after.size !== total || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs) {
throw new Error('local input changed while copying');
}
} finally { await writer.close(); }
} finally { await reader.close(); }
let target = prepared;
for (const key of input.keys.slice(0, -1)) target = target[key];
target[input.keys.at(-1)] = `${input.prefix || ''}${relative}`;
}
return { parameters: prepared, cwd: directory, cleanup };
} catch (error) {
cleanup();
if (error.code === 'E_TOOL_CALL_CANCELLED' || error.code === 'ETIMEDOUT') throw error;
throw new Error('local input could not be prepared; check file access and size');
}
}
function parameterArgs(parameters) {
const args = [];
for (const [key, value] of Object.entries(parameters)) {
const flag = `--${key.replace(/_/g, '-')}`;
if (value === true) args.push(flag);
else if (value === false) args.push(flag, 'false');
else if (value === null) args.push(flag, 'null');
else if (typeof value === 'object') args.push(flag, JSON.stringify(value));
else args.push(flag, String(value));
}
return args;
}
function redact(value) {
return String(value || '')
.replace(/("(?:access|refresh|id)[_-]?token"|"client[_-]?secret"|"api[_-]?key"|"authorization"|"password")\s*:\s*"[^"]*"/gi, '$1:"[redacted]"')
.replace(/([?&#](?:code|access_token|refresh_token|id_token|client_secret)=)[^&\s"'<>]+/gi, '$1[redacted]')
.replace(/\b((?:access|refresh|id)[_-]?token|client[_-]?secret|api[_-]?key|authorization|password)\s*[:=]\s*[^\s"'<>]+/gi, '$1=[redacted]')
.slice(0, MAX_OUTPUT_CHARS);
}
function throwIfCancelled(signal) {
if (signal?.aborted) {
if (signal.reason?.name === 'TimeoutError') throw Object.assign(new Error('local CLI call timed out'), { code: 'ETIMEDOUT' });
throw Object.assign(new Error('local CLI call was cancelled'), { code: 'E_TOOL_CALL_CANCELLED' });
}
}
function runOfficialProcess(command, args, options) {
return new Promise((resolve) => {
let child;
let timer;
let settled = false;
let terminalError;
const chunks = { stdout: [], stderr: [] };
const bytes = { stdout: 0, stderr: 0 };
const finish = (status, error = terminalError) => {
if (settled) return;
settled = true;
clearTimeout(timer);
options.signal?.removeEventListener('abort', onAbort);
child?.stdout?.destroy();
child?.stderr?.destroy();
resolve({
status, error,
stdout: Buffer.concat(chunks.stdout).toString('utf8'),
stderr: Buffer.concat(chunks.stderr).toString('utf8'),
});
};
const terminate = (code) => {
if (settled || terminalError) return;
terminalError = Object.assign(new Error(code), { code });
clearTimeout(timer);
killProcessTree(child, 'SIGKILL');
timer = setTimeout(() => finish(null), 3000);
timer.unref?.();
};
const onAbort = () => terminate('E_TOOL_CALL_CANCELLED');
try {
throwIfCancelled(options.signal);
child = spawn(command, args, {
cwd: options.cwd, env: options.env,
detached: process.platform !== 'win32', windowsHide: true,
stdio: ['ignore', 'pipe', 'pipe'],
});
} catch (error) {
finish(null, error);
return;
}
for (const stream of ['stdout', 'stderr']) {
child[stream].on('data', (data) => {
if (settled || terminalError) return;
const remaining = Math.max(0, options.maxBuffer - bytes[stream]);
if (remaining) chunks[stream].push(data.subarray(0, remaining));
bytes[stream] += Math.min(data.length, remaining);
if (data.length > remaining) terminate('ERR_CHILD_PROCESS_STDIO_MAXBUFFER');
});
}
child.once('error', (error) => finish(null, error));
child.once('close', (status) => finish(status));
timer = setTimeout(() => terminate('ETIMEDOUT'), options.timeout);
timer.unref?.();
options.signal?.addEventListener('abort', onAbort, { once: true });
if (options.signal?.aborted) onAbort();
});
}
async function runOfficial(args, options = {}, env = process.env) {
throwIfCancelled(options.signal);
await options.onProgress?.();
const manifest = configuredManifest(env);
const runner = options.runner || runOfficialProcess;
const result = await runner(env.ORKAS_NODE, [
env.ORKAS_LOCAL_CLI_NPX_CLI, '--offline', '-y', manifest.package, ...args,
], {
cwd: options.cwd || env.ORKAS_LOCAL_CLI_WORK_DIR,
env,
encoding: 'utf8',
timeout: options.timeoutMs || 60_000,
maxBuffer: MAX_OUTPUT_CHARS,
windowsHide: true,
signal: options.signal,
});
throwIfCancelled(options.signal);
const stdout = redact(result.stdout);
const permissionError = permissions.structuredPermissionFailure(result, manifest.provider);
if (manifest.provider === 'lark' && !result.error) {
const structured = larkContract.structuredFailure(result);
if (structured && (structured.code === 'connector_permission_denied' || !permissionError)) {
permissions.rememberPermissionRequest(structured, env);
throw structured;
}
}
if (permissionError) {
permissions.rememberPermissionRequest(permissionError, env);
throw permissionError;
}
if (result.error || result.status !== 0) {
const rawFailure = [result.error?.message, result.stderr, result.stdout].filter(Boolean).join('\n');
const reconnect = manifest.provider !== 'lark' && /unauthori[sz]ed|not[_ -]?(?:logged|authenticated)|credential|login|reconnect|token expired/i
.test(rawFailure);
const failure = new Error(reconnect
? `official ${manifest.executable} account is not authorized; reconnect this connector`
: `official ${manifest.executable} command failed${Number.isInteger(result.status) ? ` (exit ${result.status})` : ''}`);
failure.code = reconnect ? 'connector_reconnect_required' : 'local_cli_action_failed';
throw failure;
}
const text = stdout.trim();
if (!text) return { ok: true };
try { return JSON.parse(text); } catch { return { ok: true, output: text }; }
}
async function assertAuthorized(options = {}, env = process.env) {
throwIfCancelled(options.signal);
const manifest = configuredManifest(env);
if (options.skipPackageIntegrityCheck !== true) assertPackageIntegrityMarker(manifest, env);
if (env.ORKAS_LOCAL_CLI_SKIP_AUTH_CHECK === '1') return;
const status = await runOfficial(manifest.status(env), { ...options, timeoutMs: 30_000 }, env);
const normalized = JSON.stringify(status).toLowerCase();
if (/unauthori[sz]ed|not[_ -]?(?:logged|authenticated)|"authenticated"\s*:\s*false|"authorized"\s*:\s*false/.test(normalized)) {
throw new Error(`official ${manifest.executable} account is not authorized; reconnect this connector`);
}
}
async function inspectAction(action, options = {}, env = process.env) {
const validated = validateAction(action, env);
let schema;
if (validated.manifest.provider === 'wecom') {
schema = await runOfficial([...validated.tokens, '--schema'], { ...options, timeoutMs: 30_000 }, env);
} else if (validated.manifest.provider === 'lark') {
if (validated.tokens.some((token) => token.startsWith('+'))) {
const help = await runOfficial([...validated.tokens, '--help'], { ...options, timeoutMs: 30_000 }, env);
schema = larkContract.shortcutSchema(help, validated.cliPath);
} else {
schema = larkContract.apiSchema(
await runOfficial(['schema', validated.canonical], { ...options, timeoutMs: 30_000 }, env),
validated.canonical,
);
}
} else if (validated.manifest.provider === 'dingtalk') {
schema = await runOfficial(['schema', '--cli-path', validated.cliPath, '--compact', '-f', 'json'], {
...options, timeoutMs: 30_000,
}, env);
} else {
schema = await runOfficial([...validated.tokens, '--help'], { ...options, timeoutMs: 30_000 }, env);
}
return {
provider: validated.manifest.provider,
action: validated.canonical,
cli_path: validated.manifest.provider === 'lark' ? schema.name : validated.cliPath,
risk: validated.manifest.provider === 'xero'
? classifyXeroAction(validated.canonical)
: classifyAction(validated.canonical, schema),
schema,
};
}
async function inspectCapabilities(pathValue, options = {}, env = process.env) {
const validated = validateCapabilityPath(pathValue, env);
let schema;
if (validated.manifest.provider === 'wecom') {
schema = await runOfficial([...validated.tokens, '--schema'], { ...options, timeoutMs: 30_000 }, env);
} else if (validated.manifest.provider === 'lark') {
if (validated.tokens.length === 1 || validated.tokens.some((token) => token.startsWith('+'))) {
const help = await runOfficial([...validated.tokens, '--help'], { ...options, timeoutMs: 30_000 }, env);
schema = larkContract.capabilityCommands(help, validated.cliPath);
} else {
schema = await runOfficial(['schema', validated.canonical], { ...options, timeoutMs: 30_000 }, env);
}
} else if (validated.manifest.provider === 'dingtalk') {
schema = await runOfficial(['schema', validated.cliPath, '--compact', '-f', 'json'], {
...options, timeoutMs: 30_000,
}, env);
} else {
schema = await runOfficial([...validated.tokens, '--help'], { ...options, timeoutMs: 30_000 }, env);
}
return {
provider: validated.manifest.provider,
path: validated.canonical,
schema,
guidance: 'Continue with a returned subgroup path, or pass an exact leaf action to describe_action.',
};
}
function invocationFor(action, parameters, risk, env = process.env, inspection) {
const validated = validateAction(action, env);
const params = validatedParameters(parameters, env, inspection);
return providerInvocation(validated, params, risk, env, inspection);
}
function providerInvocation(validated, params, risk, env, inspection) {
const args = validated.manifest.provider === 'lark' && inspection
? [...inspection.cli_path.split(' '), ...larkContract.parameterArgs(params, inspection.schema)]
: validated.manifest.provider === 'wecom'
? [...validated.tokens, '--json', JSON.stringify(params)]
: [...validated.tokens, ...parameterArgs(params)];
if (validated.manifest.provider === 'lark') {
args.push('--profile', env.ORKAS_LOCAL_CLI_PROFILE, '--format', 'json');
if (risk !== 'R' && inspection?.schema?._meta?.risk === 'high-risk-write') args.push('--yes');
} else if (validated.manifest.provider === 'dingtalk') {
args.push('--format', 'json');
if (risk !== 'R') args.push('--yes');
} else if (validated.manifest.provider === 'xero') {
args.push('--profile', env.ORKAS_LOCAL_CLI_PROFILE, '--json');
}
return args;
}
async function executeAction(expectedRisk, args, options = {}, env = process.env) {
const inspection = await inspectAction(args.action, options, env);
let parameters = args.parameters;
const effectiveRisk = invocationRisk(inspection.risk, parameters, env, inspection);
if (effectiveRisk !== expectedRisk) {
throw new Error(`action risk mismatch: ${inspection.action} is ${effectiveRisk}, use ${
effectiveRisk === 'R' ? 'execute_read'
: effectiveRisk === 'W' ? 'execute_write'
: effectiveRisk === 'D' ? 'execute_destructive'
: 'execute_high_impact'
}`);
}
if (inspection.provider === 'lark' && inspection.schema._meta.source === 'cli-help') {
parameters = larkContract.shortcutParameters(validatedParameters(parameters, env, inspection), inspection.schema,
(file) => validatedParameters({ file }, env));
}
parameters = validatedParameters(parameters, env, inspection);
const inputs = localInputs(parameters, env, inspection);
const properties = parameterSchema(inspection).properties || {};
const transfer = inputs.some(input => !input.prefix)
|| Object.entries(parameters).some(([key, value]) => {
const property = properties[key] || properties[key.replace(/-/g, '_')];
return fileContract(property, inspection.provider).url && typeof value === 'string' && /^https:\/\//i.test(value);
})
|| actionTokens(inspection.action).at(-1).split(/[-_+]/).some(token => ['upload', 'download', 'import', 'export'].includes(token));
const timeoutMs = 10 * 60_000;
const deadline = new AbortController();
const signal = options.signal ? AbortSignal.any([options.signal, deadline.signal]) : deadline.signal;
const timer = setTimeout(() => deadline.abort(new DOMException('Execution deadline exceeded', 'TimeoutError')), timeoutMs);
timer.unref?.();
// Transfer progress is a liveness heartbeat, not a completion percentage.
// The host keeps a fixed ten-minute deadline regardless of these notifications.
const heartbeat = transfer && options.onProgress ? setInterval(() => { void options.onProgress(); }, 15_000) : null;
heartbeat?.unref?.();
let prepared;
try {
prepared = await prepareLocalInputs(parameters, inspection, env, signal);
if (inspection.provider === 'lark' && inspection.action === 'im.+messages-resources-download') {
const directory = options.localFileOutputDirectory;
if (typeof directory !== 'string' || !path.isAbsolute(directory)) {
throw new Error('A current conversation is required to receive this download.');
}
const real = fs.realpathSync(directory);
// This directory comes from MCP request metadata owned by the Host,
// never provider arguments. Host and child may have different temp roots.
if (!fs.statSync(real).isDirectory()
|| isWithin(fs.realpathSync(env.ORKAS_LOCAL_CLI_RUNTIME_DIR), real)) {
throw new Error('The download staging directory is not allowed.');
}
prepared.cwd = real;
}
throwIfCancelled(signal);
const invocation = providerInvocation(validateAction(inspection.action, env), prepared.parameters, effectiveRisk, env, inspection);
return {
action: inspection.action,
risk: effectiveRisk,
result: await runOfficial(invocation, { ...options, signal, timeoutMs, ...(prepared.cwd ? { cwd: prepared.cwd } : {}) }, env),
};
} finally {
clearTimeout(timer);
clearInterval(heartbeat);
prepared?.cleanup();
}
}
async function callTool(name, args = {}, options = {}, env = process.env) {
await assertAuthorized(options, env);
const manifest = configuredManifest(env);
if (name === 'list_capabilities') {
if (args.path != null && String(args.path).trim()) {
return inspectCapabilities(args.path, options, env);
}
return {
provider: manifest.provider,
official_cli: manifest.executable,
domains: manifest.domains,
execution_tools: ['execute_read', 'execute_write', 'execute_high_impact', 'execute_destructive'],
guidance: 'Call list_capabilities again with a domain or subgroup path, then call describe_action with an exact leaf action.',
};
}
if (name === 'describe_action') {
const inspection = await inspectAction(args.action, options, env);
if (inspection.provider === 'lark') {
for (const property of Object.values(inspection.schema.inputSchema.properties)) {
if (fileContract(property, 'lark').localPath && typeof property.description === 'string') {
property.description = property.description
.replace('cwd-relative local path', 'absolute local path in Orkas-approved roots')
.replace(' (absolute paths and .. are rejected)', '');
}
}
}
return inspection;
}
if (name === 'execute_read') return executeAction('R', args, options, env);
if (name === 'execute_write') return executeAction('W', args, options, env);
if (name === 'execute_high_impact') return executeAction('H', args, options, env);
if (name === 'execute_destructive') return executeAction('D', args, options, env);
throw new Error(`unknown tool: ${name}`);
}
async function main() {
const lifetime = new AbortController();
// Official CLIs share profile/token files. Preserve the synchronous adapter's
// request ordering while leaving the event loop free to receive cancellation.
let requestTail = Promise.resolve();
const runInOrder = (task) => {
const pending = requestTail.then(task);
requestTail = pending.catch(() => {});
return pending;
};
const server = new Server({ name: 'orkas-official-local-cli', version: '1.0.0' }, { capabilities: { tools: {} } });
const shutdown = () => {
lifetime.abort();
void server.close().catch(() => {});
};
process.stdin.once('end', shutdown);
process.once('SIGTERM', shutdown);
process.once('SIGINT', shutdown);
server.setRequestHandler(ListToolsRequestSchema, async (_request, extra) => {
const signal = AbortSignal.any([lifetime.signal, extra.signal]);
return runInOrder(async () => {
await assertAuthorized({ signal });
return { tools: TOOLS };
});
});
server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
try {
const signal = AbortSignal.any([lifetime.signal, extra.signal]);
let progress = 0;
const progressToken = request.params._meta?.progressToken;
const onProgress = progressToken == null ? undefined : () => extra.sendNotification({
method: 'notifications/progress', params: { progressToken, progress: ++progress },
}).catch(() => {});
const result = await runInOrder(() => callTool(request.params.name, request.params.arguments || {}, {
signal, onProgress,
localFileOutputDirectory: request.params._meta?.['orkas/local-file-output-directory'],
}));
return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
} catch (error) {
return {
isError: true,
content: [{ type: 'text', text: JSON.stringify({
error_code: error?.provider_error || error?.code === 'local_cli_contract_invalid' ? error.code
: error?.code === 'connector_reconnect_required'
|| /authoriz|login|credential|reconnect/i.test(String(error && error.message))
? 'connector_reconnect_required'
: 'local_cli_action_failed',
message: redact(error && error.message ? error.message : String(error)),
...(error?.provider_error ? { provider_error: error.provider_error } : {}),
}) }],
};
}
});
await server.connect(new StdioServerTransport());
}
module.exports = {
MANIFESTS,
TOOLS,
TOOL_POLICIES,
actionTokens,
capabilityTokens,
validateAction,
validateCapabilityPath,
assertPackageIntegrityMarker,
classifyAction,
classifyXeroAction,
invocationRisk,
redact,
validatedParameters,
invocationFor,
inspectCapabilities,
inspectAction,
executeAction,
callTool,
};
if (require.main === module) {
main().catch(() => {
process.stderr.write('local-cli-mcp-server fatal: startup failed\n');
process.exit(1);
});
}