Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

23.6 KB
Raw Blame
import debug from 'debug';

import { trackAnalyticsEvent } from '../analytics';
import { callCoreRpc } from '../coreRpcClient';
import {
  isScanBlocked,
  normalizeScanBlocked,
  type RawScanBlocked,
  type ScanBlocked,
} from './skillRegistryApi';

const log = debug('skillsApi');

/**
 * Scope a skill was discovered in.
 *
 * Mirrors `openhuman::skills::ops::WorkflowScope` on the Rust side — serialized
 * as a lowercase string (`"user" | "project" | "legacy"`).
 */
export type WorkflowScope = 'user' | 'project' | 'legacy';

/**
 * Wire-format representation of a discovered skill returned by
 * `openhuman.skills_list`.
 *
 * Paths are intentionally serialized as strings (not URLs) to avoid lossy
 * conversions on non-UTF-8 filesystems.
 */
export interface WorkflowSummary {
  /** Stable identifier — equal to `name` on the Rust side. */
  id: string;
  /** Display name, from frontmatter or directory. */
  name: string;
  /** Short prose summary from frontmatter / `description`. */
  description: string;
  /** Version string, if declared (empty otherwise). */
  version: string;
  /** Author string, if declared. */
  author: string | null;
  /** Tags declared in frontmatter metadata. */
  tags: string[];
  /** Platform compatibility hints from SKILL.md frontmatter. */
  platforms: string[];
  /** Related skills declared by the originating ecosystem. */
  relatedSkills: string[];
  /** Normalized source format hint, e.g. openhuman, hermes, legacy. */
  sourceFormat: string;
  /** Tool hint from `allowed-tools`. */
  tools: string[];
  /** Prompt files declared in the legacy manifest. */
  prompts: string[];
  /** Path to `SKILL.md` (or `skill.json`) on disk, or null if unknown. */
  location: string | null;
  /** Bundled resource files, relative to the skill root. */
  resources: string[];
  /** Where the skill came from. */
  scope: WorkflowScope;
  /** True when loaded from the legacy `skills/` layout. */
  legacy: boolean;
  /** Non-fatal parse warnings to surface in the UI. */
  warnings: string[];
}

interface WorkflowsListResult {
  workflows: RawWorkflowSummary[];
}

type RawWorkflowSummary = Omit<WorkflowSummary, 'platforms' | 'relatedSkills' | 'sourceFormat'> & {
  platforms?: string[];
  related_skills?: string[];
  relatedSkills?: string[];
  source_format?: string;
  sourceFormat?: string;
};

/**
 * Result of `openhuman.skills_read_resource`.
 */
interface WorkflowResourceContent {
  /** Echo of the requested skill id. */
  workflowId: string;
  /** Echo of the requested relative path. */
  relativePath: string;
  /** UTF-8 file contents (<= 128 KB). */
  content: string;
  /** Size of the file on disk, in bytes. */
  bytes: number;
}

interface RawWorkflowsReadResourceResult {
  workflow_id: string;
  relative_path: string;
  content: string;
  bytes: number;
}

/**
 * Parameters accepted by `openhuman.skills_create`.
 *
 * Matches the wire shape defined in `crates/openhuman-core/src/skills/schemas.rs`
 * (`SkillsCreateParams`) — `allowedTools` is rekeyed to `allowed-tools` on
 * the JSON-RPC envelope per SKILL.md frontmatter convention (with
 * `allowed_tools` accepted as an alias by the Rust deserializer).
 */
/**
 * One declared `[[inputs]]` row supplied at create time by
 * `CreateWorkflowForm.tsx`. Mirrors the Rust `SkillCreateInputDef` wire
 * shape — `description` and `type` are optional; `required` defaults
 * to `true` on the Rust side when omitted (we send it explicitly to
 * stay loud).
 */
export interface CreateWorkflowInputDef {
  name: string;
  description?: string;
  required: boolean;
  type?: 'string' | 'integer' | 'boolean';
}

export interface CreateWorkflowInput {
  name: string;
  description: string;
  /**
   * Optional trigger/goal — *when* an agent should reach for this workflow.
   * This is the workflow half of the unified form (a bare procedure md only
   * says what it does, not when to run it). Persisted to the workflow's
   * `skill.toml` `when_to_use`; falls back to `description` when omitted.
   */
  whenToUse?: string;
  scope?: WorkflowScope;
  license?: string;
  author?: string;
  tags?: string[];
  allowedTools?: string[];
  /**
   * Optional list of `[[inputs]]` rows. When non-empty the Rust side
   * writes a sibling `skill.toml` next to the generated SKILL.md so
   * the Skills Runner can render dynamic form controls per input.
   * Omit / pass `[]` to scaffold an input-less skill.
   */
  inputs?: CreateWorkflowInputDef[];
}

interface RawWorkflowsCreateResult {
  workflow: RawWorkflowSummary;
}

/**
 * Parameters accepted by `openhuman.skills_install_from_url`.
 *
 * `timeoutSecs` is optional — the Rust side defaults to 60s and caps at
 * 600s. Values outside that range are clamped server-side.
 */
interface InstallWorkflowFromUrlInput {
  url: string;
  timeoutSecs?: number;
  /** The `digest` of the blocked document the user chose "Install anyway" on. */
  acknowledgedDigest?: string;
}

/**
 * Result of `openhuman.skills_install_from_url`.
 *
 * `newWorkflows` lists skill ids that appeared post-install (diff vs the
 * pre-install snapshot). `stdout` holds a human-readable diagnostic summary
 * (bytes fetched, target path); `stderr` holds non-fatal frontmatter parse
 * warnings joined by newlines. There is no subprocess — the Rust side fetches
 * SKILL.md directly over HTTPS.
 */
export interface InstallWorkflowFromUrlResult {
  url: string;
  stdout: string;
  stderr: string;
  newWorkflows: string[];
}

export type InstallWorkflowFromUrlOutcome =
  | ({ status: 'installed' } & InstallWorkflowFromUrlResult)
  | { status: 'scan_blocked'; scan: ScanBlocked };

interface RawInstallWorkflowFromUrlResult {
  status?: 'installed';
  url: string;
  stdout: string;
  stderr: string;
  new_workflows: string[];
}

/**
 * Result of `openhuman.skill_registry_uninstall`.
 *
 * Mirrors the Rust-side `UninstallSkillOutcome`. `removedPath` is the
 * canonicalised on-disk path that was deleted — surface it in success toasts
 * so the user can confirm exactly what was removed.
 */
export interface UninstallWorkflowResult {
  name: string;
  removedPath: string;
  scope: WorkflowScope;
}

interface RawUninstallWorkflowResult {
  name: string;
  removed_path: string;
  scope: WorkflowScope;
}

interface SkillRuntimeSummary {
  runtime: 'node' | 'python' | string;
  enabled: boolean;
  available: boolean;
  source: 'system' | 'managed' | string | null;
  version: string | null;
  binary: string | null;
  binDir: string | null;
  error: string | null;
}

interface RawSkillRuntimeSummary {
  runtime: string;
  enabled: boolean;
  available: boolean;
  source: string | null;
  version: string | null;
  binary: string | null;
  bin_dir: string | null;
  error: string | null;
}

interface ResolveSkillRuntimesResult {
  runtimes: SkillRuntimeSummary[];
}

interface RawResolveSkillRuntimesResult {
  runtimes: RawSkillRuntimeSummary[];
}

interface Envelope<T> {
  data?: T;
}

function unwrapEnvelope<T>(response: Envelope<T> | T): T {
  if (response && typeof response === 'object' && 'data' in response) {
    const envelope = response as Envelope<T>;
    if (envelope.data !== undefined) {
      return envelope.data as T;
    }
  }
  return response as T;
}

function normalizeWorkflowSummary(raw: RawWorkflowSummary): WorkflowSummary {
  return {
    ...raw,
    platforms: raw.platforms ?? [],
    relatedSkills: raw.relatedSkills ?? raw.related_skills ?? [],
    sourceFormat: raw.sourceFormat ?? raw.source_format ?? (raw.legacy ? 'legacy' : 'openhuman'),
  };
}

/** Options for {@link skillsApi.listWorkflows}. */
interface ListWorkflowsOptions {
  /**
   * When `true`, also include capability skills under the `skills/` roots
   * (registry installs land there), not just `workflows/`-root automations.
   */
  includeSkills?: boolean;
}

export const skillsApi = {
  /**
   * Enumerate SKILL.md / legacy skills visible in the active workspace.
   *
   * By default returns only `workflows/`-root automations (the Automations UI
   * view). Pass `{ includeSkills: true }` to also include capability skills
   * under the `skills/` roots — the Skills Explorer uses this so
   * registry-installed skills show up in its Installed tab.
   */
  listWorkflows: async (opts?: ListWorkflowsOptions): Promise<WorkflowSummary[]> => {
    log('listWorkflows: request includeSkills=%s', opts?.includeSkills ?? false);
    const response = await callCoreRpc<Envelope<WorkflowsListResult> | WorkflowsListResult>({
      method: 'openhuman.skills_list',
      params: opts?.includeSkills ? { include_skills: true } : undefined,
    });
    const result = unwrapEnvelope(response);
    const workflows = (result?.workflows ?? []).map(normalizeWorkflowSummary);
    log('listWorkflows: response count=%d', workflows.length);
    return workflows;
  },

  /**
   * Read a single bundled resource file from a discovered skill. Rejects on
   * traversal, symlink escape, non-UTF-8 payloads, or files larger than
   * 128 KB — the caller surfaces the error string verbatim in the drawer.
   */
  readWorkflowResource: async ({
    workflowId,
    relativePath,
  }: {
    workflowId: string;
    relativePath: string;
  }): Promise<WorkflowResourceContent> => {
    log('readWorkflowResource: request workflowId=%s path=%s', workflowId, relativePath);
    const response = await callCoreRpc<
      Envelope<RawWorkflowsReadResourceResult> | RawWorkflowsReadResourceResult
    >({
      method: 'openhuman.skills_read_resource',
      params: { workflow_id: workflowId, relative_path: relativePath },
    });
    const raw = unwrapEnvelope(response);
    const normalized: WorkflowResourceContent = {
      workflowId: raw.workflow_id,
      relativePath: raw.relative_path,
      content: raw.content,
      bytes: raw.bytes,
    };
    log('readWorkflowResource: response bytes=%d', normalized.bytes);
    return normalized;
  },

  /**
   * Scaffold a new SKILL.md skill via `openhuman.skills_create`.
   *
   * The Rust side slugifies the name, writes `SKILL.md` with the supplied
   * frontmatter, and returns the freshly-discovered `WorkflowSummary` so the
   * caller can insert the new row into the grid without a full refetch.
   */
  createWorkflow: async (input: CreateWorkflowInput): Promise<WorkflowSummary> => {
    log('createWorkflow: request name=%s scope=%s', input.name, input.scope ?? 'default');
    const response = await callCoreRpc<
      Envelope<RawWorkflowsCreateResult> | RawWorkflowsCreateResult
    >({
      method: 'openhuman.skills_create',
      params: {
        name: input.name,
        description: input.description,
        ...(input.whenToUse !== undefined && input.whenToUse.trim().length > 0
          ? { when_to_use: input.whenToUse }
          : {}),
        ...(input.scope !== undefined ? { scope: input.scope } : {}),
        ...(input.license !== undefined ? { license: input.license } : {}),
        ...(input.author !== undefined ? { author: input.author } : {}),
        ...(input.tags !== undefined ? { tags: input.tags } : {}),
        ...(input.allowedTools !== undefined ? { 'allowed-tools': input.allowedTools } : {}),
        ...(input.inputs !== undefined && input.inputs.length > 0 ? { inputs: input.inputs } : {}),
      },
    });
    const raw = unwrapEnvelope(response);
    const workflow = normalizeWorkflowSummary(raw.workflow);
    log('createWorkflow: response id=%s', workflow.id);
    return workflow;
  },

  /**
   * Edit an existing workflow via `openhuman.skills_update`. Same payload
   * shape as create; the Rust side overwrites the workflow at the resolved
   * slug — rewriting frontmatter + workflow.toml while preserving the
   * hand-authored SKILL.md/WORKFLOW.md body.
   */
  updateWorkflow: async (input: CreateWorkflowInput): Promise<WorkflowSummary> => {
    log('updateWorkflow: request name=%s scope=%s', input.name, input.scope ?? 'default');
    const response = await callCoreRpc<
      Envelope<RawWorkflowsCreateResult> | RawWorkflowsCreateResult
    >({
      method: 'openhuman.skills_update',
      params: {
        name: input.name,
        description: input.description,
        ...(input.whenToUse !== undefined && input.whenToUse.trim().length > 0
          ? { when_to_use: input.whenToUse }
          : {}),
        ...(input.scope !== undefined ? { scope: input.scope } : {}),
        ...(input.license !== undefined ? { license: input.license } : {}),
        ...(input.author !== undefined ? { author: input.author } : {}),
        ...(input.tags !== undefined ? { tags: input.tags } : {}),
        ...(input.allowedTools !== undefined ? { 'allowed-tools': input.allowedTools } : {}),
        ...(input.inputs !== undefined && input.inputs.length > 0 ? { inputs: input.inputs } : {}),
      },
    });
    const raw = unwrapEnvelope(response);
    const workflow = normalizeWorkflowSummary(raw.workflow);
    log('updateWorkflow: response id=%s', workflow.id);
    return workflow;
  },

  /**
   * Install a remote SKILL.md by URL via `openhuman.skills_install_from_url`.
   *
   * The Rust side fetches the SKILL.md directly over HTTPS (no subprocess,
   * no Node toolchain required), validates the frontmatter, and writes it
   * into the user-scope skills directory. URL must be https, resolve to a
   * public host, and point at a single `.md` file; `github.com/.../blob/...`
   * is normalised to its `raw.githubusercontent.com` equivalent. Size is
   * capped at 1 MiB; timeout default 60s, max 600s.
   */
  installWorkflowFromUrl: async (
    input: InstallWorkflowFromUrlInput
  ): Promise<InstallWorkflowFromUrlOutcome> => {
    const digest = input.acknowledgedDigest?.trim();
    log('installWorkflowFromUrl: request url=%s acknowledged=%s', input.url, Boolean(digest));
    const response = await callCoreRpc<
      | Envelope<RawInstallWorkflowFromUrlResult | RawScanBlocked>
      | RawInstallWorkflowFromUrlResult
      | RawScanBlocked
    >({
      method: 'openhuman.skills_install_from_url',
      params: {
        url: input.url,
        ...(input.timeoutSecs !== undefined ? { timeout_secs: input.timeoutSecs } : {}),
        ...(digest ? { acknowledged_digest: digest } : {}),
      },
    });
    const raw = unwrapEnvelope(response);
    if (isScanBlocked(raw)) {
      const scan = normalizeScanBlocked(raw);
      log('installWorkflowFromUrl: scan_blocked findings=%d', scan.findings.length);
      return { status: 'scan_blocked', scan };
    }
    const normalized: InstallWorkflowFromUrlOutcome = {
      status: 'installed',
      url: raw.url,
      stdout: raw.stdout,
      stderr: raw.stderr,
      newWorkflows: raw.new_workflows ?? [],
    };
    log(
      'installWorkflowFromUrl: response new=%d stdout=%d stderr=%d',
      normalized.newWorkflows.length,
      normalized.stdout.length,
      normalized.stderr.length
    );
    return normalized;
  },

  /**
   * Remove an installed user-scope SKILL.md skill via `openhuman.skill_registry_uninstall`.
   *
   * Only user-scope installs (`~/.openhuman/skills/<name>/`) are supported.
   * Project-scope and legacy skills are read-only — trying to uninstall one
   * returns a backend error surfaced as a rejected promise. The Rust side
   * canonicalises paths and refuses names with separators / traversal
   * sequences / anything outside the skills root.
   */
  uninstallWorkflow: async (name: string): Promise<UninstallWorkflowResult> => {
    log('uninstallWorkflow: request name=%s', name);
    const response = await callCoreRpc<
      Envelope<RawUninstallWorkflowResult> | RawUninstallWorkflowResult
    >({ method: 'openhuman.skill_registry_uninstall', params: { name } });
    const raw = unwrapEnvelope(response);
    const normalized: UninstallWorkflowResult = {
      name: raw.name,
      removedPath: raw.removed_path,
      scope: raw.scope,
    };
    log(
      'uninstallWorkflow: response name=%s removedPath=%s',
      normalized.name,
      normalized.removedPath
    );
    return normalized;
  },

  /**
   * Fetch the declared `[[inputs]]` for a single skill plus its display
   * metadata. Lightweight companion to `listWorkflows` — `WorkflowSummary` rows
   * (used by the catalog grid) deliberately don't include input
   * declarations, so the Skills Runner panel calls this once when the
   * user picks a skill from the dropdown so it can render the right form
   * controls.
   */
  describeWorkflow: async (workflowId: string): Promise<WorkflowDescription> => {
    log('describeWorkflow: request workflowId=%s', workflowId);
    const response = await callCoreRpc<Envelope<WorkflowDescription> | WorkflowDescription>({
      method: 'openhuman.skills_describe',
      params: { workflow_id: workflowId },
    });
    const raw = unwrapEnvelope(response);
    log('describeWorkflow: response inputs=%d', raw.inputs.length);
    return raw;
  },

  /**
   * Fire-and-forget invocation of `openhuman.skill_runtime_run`. Returns
   * immediately with the new background run's `run_id`, the canonical
   * skill/workflow id, and the log path the run is streaming into; the actual
   * autonomous work continues in the background and finishes with
   * status `DONE` / `STOPPED` / `DEGENERATE` / `FAILED` in the run log.
   */
  runWorkflow: async (
    workflowId: string,
    inputs: Record<string, unknown>
  ): Promise<WorkflowRunStarted> => {
    log('runWorkflow: request workflowId=%s', workflowId);
    const response = await callCoreRpc<Envelope<RawSkillRunStarted> | RawSkillRunStarted>({
      method: 'openhuman.skill_runtime_run',
      params: { skill_id: workflowId, inputs },
    });
    const raw = unwrapEnvelope(response);
    const normalized: WorkflowRunStarted = {
      run_id: raw.run_id,
      status: raw.status,
      workflow_id: raw.workflow_id ?? raw.skill_id,
      log: raw.log,
    };
    log('runWorkflow: response runId=%s log=%s', normalized.run_id, normalized.log);
    trackAnalyticsEvent('automation_run_started', { automation_kind: 'skill' });
    return normalized;
  },
  /**
   * Request cancellation of an in-flight run via `openhuman.skill_runtime_cancel`.
   * Returns `true` if a live run with this id was found and signalled; the run
   * stops at its next await and lands a CANCELLED footer.
   */
  cancelRun: async (runId: string): Promise<boolean> => {
    log('cancelRun: request runId=%s', runId);
    const response = await callCoreRpc<Envelope<{ cancelled: boolean }> | { cancelled: boolean }>({
      method: 'openhuman.skill_runtime_cancel',
      params: { run_id: runId },
    });
    const raw = unwrapEnvelope(response);
    log('cancelRun: response cancelled=%s', raw.cancelled);
    if (raw.cancelled) {
      trackAnalyticsEvent('automation_run_cancelled', { automation_kind: 'skill' });
    }
    return raw.cancelled;
  },

  /**
   * Read a slice of a skill run's streaming log file by run_id. Pass
   * `offset` to tail forward — the returned `offset` is the cursor for
   * the next call. Stop polling once `complete: true` (footer landed).
   */
  readRunLog: async (runId: string, offset?: number, maxBytes?: number): Promise<RunLogSlice> => {
    log(
      'readRunLog: request runId=%s offset=%s maxBytes=%s',
      runId,
      offset ?? 0,
      maxBytes ?? 'default'
    );
    const params: Record<string, unknown> = { run_id: runId };
    if (offset !== undefined) params.offset = offset;
    if (maxBytes !== undefined) params.max_bytes = maxBytes;
    const response = await callCoreRpc<Envelope<RunLogSlice> | RunLogSlice>({
      method: 'openhuman.skill_runtime_read_run_log',
      params,
    });
    const raw = unwrapEnvelope(response);
    log('readRunLog: response bytes=%d eof=%s complete=%s', raw.bytes_read, raw.eof, raw.complete);
    return raw;
  },

  /**
   * Recent autonomous skill runs from `<workspace>/skills/.runs/`. Sorted
   * by start time descending. Pass `workflowId` to filter to one skill,
   * omit for cross-skill. `limit` defaults to 20 (max 100).
   */
  recentRuns: async (workflowId?: string, limit?: number): Promise<ScannedRun[]> => {
    log('recentRuns: request workflowId=%s limit=%s', workflowId ?? '*', limit ?? 'default');
    const params: Record<string, unknown> = {};
    if (workflowId !== undefined) params.skill_id = workflowId;
    if (limit !== undefined) params.limit = limit;
    const response = await callCoreRpc<Envelope<{ runs: ScannedRun[] }> | { runs: ScannedRun[] }>({
      method: 'openhuman.skill_runtime_recent_runs',
      params,
    });
    const raw = unwrapEnvelope(response);
    log('recentRuns: response count=%d', raw.runs.length);
    return raw.runs;
  },

  /** Probe whether the host Node.js and Python executables are available on PATH. */
  resolveRuntimes: async (
    runtime: 'all' | 'node' | 'python' = 'all'
  ): Promise<ResolveSkillRuntimesResult> => {
    log('resolveRuntimes: request runtime=%s', runtime);
    const response = await callCoreRpc<
      Envelope<RawResolveSkillRuntimesResult> | RawResolveSkillRuntimesResult
    >({
      method: 'openhuman.skill_runtime_resolve_runtimes',
      params: runtime === 'all' ? {} : { runtime },
    });
    const raw = unwrapEnvelope(response);
    const result: ResolveSkillRuntimesResult = {
      runtimes: (raw.runtimes ?? []).map(item => ({
        runtime: item.runtime,
        enabled: item.enabled,
        available: item.available,
        source: item.source,
        version: item.version,
        binary: item.binary,
        binDir: item.bin_dir,
        error: item.error,
      })),
    };
    log('resolveRuntimes: response count=%d', result.runtimes.length);
    return result;
  },
};

/**
 * One input declaration from a skill's `[[inputs]]` block, returned by
 * `openhuman.skills_describe`. The FE renders one form control per entry:
 * `string`/`integer`/`boolean` map to text/number/checkbox controls.
 */
export interface WorkflowInputDescription {
  name: string;
  description: string;
  required: boolean;
  /** Type hint from `[[inputs]].type`. */
  type: string;
}

/** Wire shape returned by `openhuman.skills_describe`. */
export interface WorkflowDescription {
  id: string;
  display_name: string;
  when_to_use: string;
  inputs: WorkflowInputDescription[];
}

/** Wire shape returned by `openhuman.skill_runtime_run` (fire-and-forget). */
export interface WorkflowRunStarted {
  run_id: string;
  status: string; // "started"
  workflow_id: string;
  log: string; // absolute path to the streaming log
}

interface RawSkillRunStarted {
  run_id: string;
  status: string;
  workflow_id?: string;
  skill_id: string;
  log: string;
}

/**
 * Slice of a run log file returned by `openhuman.skill_runtime_read_run_log`.
 * Mirrors `crate::skills::run_log::RunLogSlice`. The FE
 * passes the returned `offset` as the next call's `offset` to tail
 * forward; polling can stop once `complete: true` (the `--- result ---`
 * footer has landed in the file).
 */
export interface RunLogSlice {
  /** New read cursor — next call's `offset`. */
  offset: number;
  bytes_read: number;
  content: string;
  /** True if the read reached end-of-file (may still be incomplete). */
  eof: boolean;
  /** True once the run footer landed in the file. FE stops polling. */
  complete: boolean;
}

/**
 * One run entry returned by `openhuman.skill_runtime_recent_runs`. Wire shape
 * mirrors `crate::skills::run_log::ScannedRun`. `status` is
 * `"RUNNING"` while the run hasn't written its `--- result ---` footer
 * yet; after the footer lands it becomes `"DONE"` / `"STOPPED"` /
 * `"DEGENERATE"` / `"FAILED"`. `"STOPPED"` means the harness ended the run
 * early (failure breaker, deadline wind-down or iteration cap).
 */
export interface ScannedRun {
  run_id: string;
  workflow_id: string;
  /** RFC3339-with-trailing-`UTC` timestamp from the log header. */
  started: string;
  status: 'RUNNING' | 'DONE' | 'STOPPED' | 'DEGENERATE' | 'FAILED' | string;
  /** Footer `duration: <ms> ms`. Null while running. */
  duration_ms: number | null;
  /** Footer `finished:` timestamp. Null while running. */
  finished: string | null;
  /** Absolute path to the streaming log file. */
  log_path: string;
}