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.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
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 };