Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

6.5 KB
Raw Blame
import path from "node:path";
import { parse as parseYaml } from "yaml";
import { readBoundedRegularFile } from "@/lib/host/bounded-read";
import type {
  SkillContract, SkillContractMode, SkillContractSourceOfTruth, SkillContractRefresh,
  SkillContractConfirmation, SkillContractConcurrency, SkillContractPresentationAuthority,
} from "./skill-contract-types";

const CONTRACT_FILE = "contract.yaml";
const CONTRACT_MAX_BYTES = 32 * 1024;
const MODES = new Set(["read", "write", "execute", "mixed"]);
const SOURCES = new Set(["live", "local", "snapshot", "mixed"]);
const REFRESH = new Set(["always", "before-write", "contextual"]);
const RISKS = new Set(["low", "medium", "high"]);
const CONFIRMATIONS = new Set(["none", "contextual", "explicit"]);
const CONCURRENCY = new Set(["none", "hash", "revision", "compare", "contextual"]);
const AUTHORITIES = new Set(["tool", "model", "hybrid"]);

const object = (value: unknown): value is Record<string, unknown> => Boolean(value && typeof value === "object" && !Array.isArray(value));
const strings = (value: unknown, field: string, required = false): string[] | undefined => {
  if (value === undefined && !required) return undefined;
  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim())) throw new Error(`${field} must be a non-empty string array`);
  return value.map((item) => item.trim());
};
const oneOf = (value: unknown, allowed: Set<string>, field: string): string => {
  if (typeof value !== "string" || !allowed.has(value)) throw new Error(`${field} must be one of: ${[...allowed].join(", ")}`);
  return value;
};
const optionalString = (value: unknown, field: string): string | undefined => {
  if (value === undefined) return undefined;
  if (typeof value !== "string" || !value.trim()) throw new Error(`${field} must be a non-empty string`);
  return value.trim();
};

/** Parse the portable, execution-neutral contract that accompanies trusted skills. */
export function parseSkillContract(value: unknown): SkillContract {
  if (!object(value)) throw new Error("skill contract must be an object");
  if (value.version !== 1) throw new Error("skill contract version must be 1");
  if (!object(value.routing)) throw new Error("skill contract routing is required");
  if (!object(value.context)) throw new Error("skill contract context is required");

  const routing = {
    use_when: strings(value.routing.use_when, "routing.use_when", true)!,
    do_not_use_when: strings(value.routing.do_not_use_when, "routing.do_not_use_when", true)!,
    ...(value.routing.fallback === undefined ? {} : typeof value.routing.fallback === "boolean" ? { fallback: value.routing.fallback } : (() => { throw new Error("routing.fallback must be boolean"); })()),
    ...(strings(value.routing.prefer_over, "routing.prefer_over") ? { prefer_over: strings(value.routing.prefer_over, "routing.prefer_over")! } : {}),
    ...(strings(value.routing.handoff_to, "routing.handoff_to") ? { handoff_to: strings(value.routing.handoff_to, "routing.handoff_to")! } : {}),
  };
  const context = {
    target: optionalString(value.context.target, "context.target") ?? (() => { throw new Error("context.target is required"); })(),
    mode: oneOf(value.context.mode, MODES, "context.mode") as SkillContractMode,
    ...(optionalString(value.context.actor, "context.actor") ? { actor: optionalString(value.context.actor, "context.actor")! } : {}),
  };

  let lifecycle: SkillContract["lifecycle"];
  if (value.lifecycle !== undefined) {
    if (!object(value.lifecycle)) throw new Error("lifecycle must be an object");
    lifecycle = {
      ...(strings(value.lifecycle.discover, "lifecycle.discover") ? { discover: strings(value.lifecycle.discover, "lifecycle.discover")! } : {}),
      ...(strings(value.lifecycle.validate, "lifecycle.validate") ? { validate: strings(value.lifecycle.validate, "lifecycle.validate")! } : {}),
      ...(strings(value.lifecycle.verify, "lifecycle.verify") ? { verify: strings(value.lifecycle.verify, "lifecycle.verify")! } : {}),
    };
  }

  let state: SkillContract["state"];
  if (value.state !== undefined) {
    if (!object(value.state)) throw new Error("state must be an object");
    state = {
      source_of_truth: oneOf(value.state.source_of_truth, SOURCES, "state.source_of_truth") as SkillContractSourceOfTruth,
      refresh: oneOf(value.state.refresh, REFRESH, "state.refresh") as SkillContractRefresh,
    };
  }

  let safety: SkillContract["safety"];
  if (value.safety !== undefined) {
    if (!object(value.safety)) throw new Error("safety must be an object");
    safety = {
      risk: oneOf(value.safety.risk, RISKS, "safety.risk") as "low" | "medium" | "high",
      confirmation: oneOf(value.safety.confirmation, CONFIRMATIONS, "safety.confirmation") as SkillContractConfirmation,
      concurrency: oneOf(value.safety.concurrency, CONCURRENCY, "safety.concurrency") as SkillContractConcurrency,
    };
  }

  let presentation: SkillContract["presentation"];
  if (value.presentation !== undefined) {
    if (!object(value.presentation)) throw new Error("presentation must be an object");
    presentation = {
      authority: oneOf(value.presentation.authority, AUTHORITIES, "presentation.authority") as SkillContractPresentationAuthority,
      ...(optionalString(value.presentation.renderer, "presentation.renderer") ? { renderer: optionalString(value.presentation.renderer, "presentation.renderer")! } : {}),
    };
  }

  return { version: 1, routing, context, ...(lifecycle ? { lifecycle } : {}), ...(state ? { state } : {}), ...(safety ? { safety } : {}), ...(presentation ? { presentation } : {}) };
}

export async function readSkillContract(skillDir: string): Promise<SkillContract | undefined> {
  const raw = await readBoundedRegularFile(path.join(skillDir, CONTRACT_FILE), CONTRACT_MAX_BYTES, skillDir);
  if (!raw) return undefined;
  return parseSkillContract(parseYaml(raw));
}

export function compactSkillContract(contract: SkillContract) {
  return {
    target: contract.context.target,
    mode: contract.context.mode,
    useWhen: contract.routing.use_when.slice(0, 4),
    doNotUse: contract.routing.do_not_use_when.slice(0, 4),
    handoffTo: contract.routing.handoff_to?.slice(0, 4) ?? [],
    fallback: contract.routing.fallback === true,
    risk: contract.safety?.risk,
    confirmation: contract.safety?.confirmation,
    concurrency: contract.safety?.concurrency,
    sourceOfTruth: contract.state?.source_of_truth,
    refresh: contract.state?.refresh,
    discover: contract.lifecycle?.discover ?? [],
    validate: contract.lifecycle?.validate ?? [],
    verify: contract.lifecycle?.verify ?? [],
  };
}