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.

5.4 KB
Raw Blame
import type { AuthorizationGrant } from "@/lib/capabilities/authorization-grant";
import type { TenantContext } from "@/lib/tenancy/authority";
import type { AuditAction } from "@/lib/contracts/audit";
import type { CapabilityRuntime } from "./runtime";
import type { Scope } from "./scope";

export type CapabilityToolProfile = "full" | "chatgpt";

export type { McpContent as CapabilityContent } from "@/lib/contracts/mcp-content";
import type { McpContent as CapabilityContent } from "@/lib/contracts/mcp-content";

export interface CapabilityDirectResult {
  __mcpDirect: true;
  content: CapabilityContent[];
  isError?: boolean;
  /** Optional safe structured projection for transports that advertise an output schema.
   * Never put binary/base64 payloads or secrets here. */
  structuredContent?: Record<string, unknown>;
}

// UI-only capability data is deliberately not a property of the result. Generic
// JSON serialization, logs, Alfa, pipelines and model runtimes cannot copy it.
const PRIVATE_RESULT_META = new WeakMap<object, Record<string, unknown>>();
export const capabilityPrivateMeta = (result: object) => PRIVATE_RESULT_META.get(result);

/** Compatibility marker stays __mcpDirect until the public MCP result contract is versioned. */
export function capabilityDirect(
  content: CapabilityContent[],
  isError = false,
  structuredContent?: Record<string, unknown>,
  privateMeta?: Record<string, unknown>,
): CapabilityDirectResult {
  const result: CapabilityDirectResult = { __mcpDirect: true, content, ...(isError ? { isError: true } : {}), ...(structuredContent ? { structuredContent } : {}) };
  if (privateMeta) PRIVATE_RESULT_META.set(result, privateMeta);
  return result;
}

export function isCapabilityDirectResult(value: unknown): value is CapabilityDirectResult {
  return Boolean(value && typeof value === "object" && (value as CapabilityDirectResult).__mcpDirect === true);
}

export type CapabilityActionContract = {
  /** Contract version; omitted on declarations and normalized to 1 for transport metadata. */
  version?: 1;
  phase?: "discover" | "read" | "validate" | "execute" | "mutate" | "verify";
  /** Semantic target/surface such as project-mcp, filesystem-text, workflow, or artifact-ingress. */
  target?: string;
  sourceOfTruth?: "live" | "local" | "snapshot" | "provider";
  /** Named capabilities or checks that should precede this action. */
  discover?: string[];
  /** Validator/policy identifiers. They are metadata, not arbitrary commands. */
  validators?: string[];
  /** Named read/status capabilities expected after mutation/execution. */
  verify?: string[];
  confirmation?: "none" | "contextual" | "explicit";
  concurrency?: "none" | "hash" | "revision" | "compare" | "provider" | "contextual";
  presentation?: "structured" | "tool-owned" | "ui-owned" | "hybrid";
};

export interface CapabilityRunContext {
  signal?:AbortSignal;
  liveAuthorization?:()=>Promise<void>;
  tenantContext?: TenantContext;
  actor?: string;
  principal?: string;
  authorizationGrant?: AuthorizationGrant;
  sessionId?: string;
  scope: Scope;
  workflowId?: string;
  workflowActor?: string;
  recipeActor?: string;
  allowedTools?: readonly string[];
  toolArgumentConstraints?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
  capabilities?: CapabilityRuntime;
  toolProfile?: CapabilityToolProfile;
}

/**
 * Transport-neutral executable capability. MCP-specific metadata is kept as an
 * optional extension because MCP is one adapter over this catalog, not its owner.
 */
export interface CapabilityTool {
  name: string;
  title?: string;
  description: string;
  chatgptDescription?: string;
  scope: Scope;
  inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[] };
  outputSchema?: Record<string, unknown>;
  toStructuredContent?: (result: unknown) => Record<string, unknown> | undefined;
  annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean; openWorldHint?: boolean; idempotentHint?: boolean };
  securitySchemes?: Array<{ type: "oauth2"; scopes: string[] } | { type: "noauth" }>;
  meta?: Record<string, unknown>;
  /** Optional compact lifecycle contract surfaced to clients as mso/actionContract metadata. */
  actionContract?: CapabilityActionContract;
  run: (args: Record<string, unknown>, context: CapabilityRunContext) => Promise<unknown>;
  audit?: {
    action: AuditAction;
    targetArg?: string;
    outcome?: (result: unknown) => { ok: boolean; action?: AuditAction; detail?: string };
  };
  result?: { maxTextBytes?: number; overflowHint?: string };
  limit?: { max: number; windowMs: number; keyArg?: string; key: string; actionLimits?: Readonly<Record<string, { max: number; windowMs: number }>> };
}

export const str = (args: Record<string, unknown>, key: string): string => {
  const value = args[key];
  if (typeof value !== "string" || !value) throw new Error(`${key} must be a non-empty string`);
  return value;
};
export const opt = (args: Record<string, unknown>, key: string): string | undefined =>
  typeof args[key] === "string" && args[key] ? (args[key] as string) : undefined;
export const S = (properties: Record<string, unknown>, required?: string[]) =>
  ({ type: "object" as const, properties, ...(required ? { required } : {}) });
export const PATH_P = { path: { type: "string", description: "Absolute path on the VPS, or ~/… for the owner's home." } };
export const READ_ONLY = { readOnlyHint: true, idempotentHint: true };