@tealbrick/avm 0.1.0

package/dist/client/config.js

@@ -0,0 +1,257 @@
+import { z } from "zod";
+export const id = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/);
+const workspace = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
+const user = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/);
+const nonnegative = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const publicValue = z
+    .string()
+    .min(1)
+    .max(512)
+    .regex(/^[^\0\r\n]+$/);
+const provider = z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/);
+const positive = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const path = z
+    .string()
+    .regex(/^\/[A-Za-z0-9_./ -]+$/)
+    .max(4096);
+const queue = {
+    weight: positive.optional(),
+    concurrentHeavyWork: nonnegative.optional(),
+    queuePolicy: z.enum(["fair", "fifo", "reject"]).optional(),
+};
+export const administrationSchema = z.discriminatedUnion("operation", [
+    z
+        .object({
+        operation: z.literal("tenantSync"),
+        workspace,
+        displayName: publicValue.optional(),
+        principalId: user.optional(),
+        issuer: z.url().optional(),
+        subject: publicValue.optional(),
+        role: z.enum(["member", "admin", "operator"]).default("member"),
+        ...queue,
+    })
+        .strict(),
+    z
+        .object({
+        operation: z.literal("ingressPut"),
+        provider,
+        externalIdentity: publicValue,
+        worker: id,
+        channelScope: publicValue.optional(),
+        metadataFile: path.optional(),
+    })
+        .strict(),
+    z.object({ operation: z.literal("ingressRevoke"), identityId: id }).strict(),
+    z
+        .object({
+        operation: z.literal("ingressWake"),
+        provider,
+        externalIdentity: publicValue,
+        eventId: publicValue,
+        channelScope: publicValue.optional(),
+        payloadFile: path.optional(),
+        correlationId: publicValue.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        operation: z.literal("ingressComplete"),
+        wakeId: id,
+        error: publicValue.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        operation: z.literal("resize"),
+        worker: id,
+        memoryTargetMiB: positive,
+    })
+        .strict(),
+    z
+        .object({
+        operation: z.literal("workspacePut"),
+        workspace,
+        displayName: z
+            .string()
+            .min(1)
+            .max(256)
+            .regex(/^[^\0\r\n]+$/)
+            .optional(),
+        ...queue,
+    })
+        .strict(),
+    z.object({ operation: z.literal("workspaceDisable"), workspace }).strict(),
+    z
+        .object({
+        operation: z.literal("userPut"),
+        user,
+        workspace,
+        role: z.enum(["member", "admin", "operator"]),
+    })
+        .strict(),
+    z
+        .object({
+        operation: z.literal("ownerSet"),
+        worker: id,
+        workspace,
+        user: user.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        operation: z.literal("shareGrant"),
+        worker: id,
+        grantee: z.discriminatedUnion("kind", [
+            z.object({ kind: z.literal("workspace"), id: workspace }).strict(),
+            z.object({ kind: z.literal("user"), id: user }).strict(),
+        ]),
+        allow: z
+            .array(z.enum([
+            "status",
+            "exec",
+            "start",
+            "stop",
+            "ssh",
+            "logs",
+            "events",
+            "runs",
+            "assignments",
+            "schedule",
+            "capabilities",
+            "auth",
+            "leases",
+            "resident",
+            "wake",
+            "cool",
+            "list",
+            "inventory",
+            "monitor",
+            "roles",
+            "ingress",
+        ]))
+            .min(1),
+    })
+        .strict(),
+    z
+        .object({ operation: z.literal("shareRevoke"), worker: id, shareId: id })
+        .strict(),
+    z.object({ operation: z.literal("residentSet"), worker: id }).strict(),
+    z
+        .object({
+        operation: z.literal("wake"),
+        worker: id,
+        reason: z.string().min(1).max(256).optional(),
+        source: z
+            .enum(["cli", "schedule", "control-plane", "delegation"])
+            .default("cli"),
+        externalEventId: id.optional(),
+        idempotencyKey: id,
+    })
+        .strict(),
+    z.object({ operation: z.literal("cool"), worker: id }).strict(),
+    z
+        .object({
+        operation: z.literal("poolPolicySet"),
+        cpuPercent: positive.optional(),
+        memoryMaxBytes: positive.optional(),
+        memoryHighBytes: positive.optional(),
+        hostMemoryReserveBytes: nonnegative.optional(),
+        launchReserveBytes: nonnegative.optional(),
+    })
+        .strict(),
+]);
+export const policySchema = z
+    .object({
+    lifecycle: z
+        .array(z
+        .object({
+        worker: id,
+        operations: z.array(z.enum(["start", "stop", "promote", "destroy"])),
+    })
+        .strict())
+        .default([]),
+    spawns: z
+        .array(z
+        .object({
+        worker: id,
+        profile: z.enum(["light", "small", "standard", "browser"]),
+        mode: z.enum(["ephemeral", "durable"]),
+        harnesses: z.array(z.string()).optional(),
+        bundles: z.array(z.string()).optional(),
+        capabilities: z.array(z.string()).optional(),
+        mcps: z.array(z.string()).optional(),
+        plugins: z.array(z.string()).optional(),
+        auth: z
+            .array(z
+            .string()
+            .regex(/^[a-z][a-z0-9_-]*=(none|local)$|^codex=shared$/))
+            .optional(),
+    })
+        .strict())
+        .default([]),
+    commands: z
+        .array(z
+        .object({
+        worker: id,
+        command: id,
+        argv: z
+            .array(z
+            .string()
+            .max(8192)
+            .refine((v) => !v.includes("\0")))
+            .min(1)
+            .max(100),
+    })
+        .strict())
+        .default([]),
+    administration: z
+        .array(z.object({ name: id, request: administrationSchema }).strict())
+        .default([]),
+})
+    .strict();
+export const connectionSchema = z
+    .object({
+    target: z
+        .string()
+        .regex(/^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?[A-Za-z0-9][A-Za-z0-9.-]*$/),
+    mode: z.enum(["operator", "paired"]).default("operator"),
+    sudo: z.boolean().default(false),
+    identityFile: path.optional(),
+    identityTokenFile: path.optional(),
+    timeoutMs: z.number().int().min(1).max(300000).default(30000),
+    policy: policySchema.default({
+        lifecycle: [],
+        spawns: [],
+        commands: [],
+        administration: [],
+    }),
+})
+    .strict()
+    .refine((c) => c.mode !== "paired" ||
+    (c.target.startsWith("agentvm-client@") &&
+        !c.sudo &&
+        !!c.identityFile &&
+        !c.identityTokenFile), {
+    message: "Paired mode requires agentvm-client@host and its bound SSH identity file and disallows sudo or identity token overrides",
+});
+/** The operator selects one connection; tools cannot choose another identity or policy. */
+export const avmConfigSchema = z.union([
+    connectionSchema,
+    z
+        .object({ selectedProfile: id, profiles: z.record(id, connectionSchema) })
+        .strict()
+        .transform((c, ctx) => {
+        const selected = Object.hasOwn(c.profiles, c.selectedProfile)
+            ? c.profiles[c.selectedProfile]
+            : undefined;
+        if (!selected) {
+            ctx.addIssue({
+                code: "custom",
+                message: "Unknown AVM connection profile",
+            });
+            return z.NEVER;
+        }
+        return selected;
+    }),
+]);

package/dist/client/index.d.ts

@@ -0,0 +1,126 @@
+import type { AdministrationRequest } from "./config.js";
+export { avmConfigSchema, connectionSchema, policySchema, administrationSchema, } from "./config.js";
+export type { AvmConfig, AdministrationRequest } from "./config.js";
+export declare const AVMM_COMPATIBILITY: {
+    readonly version: "0.13.0-alpha.2";
+    readonly revision: "75078743b9bfc2ba268f1fdeea74f298983dfac4";
+};
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type ReadRequest = {
+    operation: "doctor" | "inventory" | "workers" | "bundles" | "monitor" | "poolStatus" | "poolPressure" | "poolQueue" | "poolPolicy" | "workspaces" | "users" | "resident";
+} | {
+    operation: "workerStatus" | "capabilities" | "owner" | "shares";
+    worker: string;
+} | {
+    operation: "runs";
+    limit?: number;
+} | {
+    operation: "events";
+    limit?: number;
+    worker?: string;
+    event?: string;
+    runId?: string;
+} | {
+    operation: "workspace" | "user";
+    id: string;
+} | {
+    operation: "ingress";
+    worker?: string;
+} | {
+    operation: "runStatus";
+    runId: string;
+};
+export type SpawnGrant = {
+    worker: string;
+    profile: "light" | "small" | "standard" | "browser";
+    mode: "ephemeral" | "durable";
+    mcps?: readonly string[];
+    plugins?: readonly string[];
+    auth?: readonly string[];
+    harnesses?: readonly string[];
+    bundles?: readonly string[];
+    capabilities?: readonly string[];
+};
+export type MutationRequest = {
+    operation: "configured";
+    action: string;
+} | {
+    operation: "spawn";
+    worker: string;
+} | {
+    operation: "start" | "stop" | "promote" | "destroy";
+    worker: string;
+} | {
+    operation: "exec";
+    worker: string;
+    command: string;
+};
+export type Request = ReadRequest | MutationRequest;
+export interface CommandGrant {
+    worker: string;
+    command: string;
+    argv: readonly string[];
+}
+export interface Policy {
+    administration?: readonly {
+        name: string;
+        request: AdministrationRequest;
+    }[];
+    spawns?: readonly SpawnGrant[];
+    lifecycle?: readonly {
+        worker: string;
+        operations: readonly ("start" | "stop" | "promote" | "destroy")[];
+    }[];
+    commands?: readonly CommandGrant[];
+}
+export interface TransportResult {
+    stdout: string;
+    exitCode: number;
+}
+export interface Transport {
+    run(argv: readonly string[], options: {
+        signal: AbortSignal;
+    }): Promise<TransportResult>;
+}
+export type ErrorCode = "INVALID_REQUEST" | "DENIED" | "TIMEOUT" | "CANCELLED" | "TRANSPORT" | "PROTOCOL" | "REMOTE" | "GUEST_FAILED" | "OUTPUT_LIMIT";
+/** Errors intentionally exclude command arguments, remote messages, stdout and stderr. */
+export declare class AvmError extends Error {
+    readonly code: ErrorCode;
+    readonly exitCode?: number | undefined;
+    constructor(code: ErrorCode, exitCode?: number | undefined);
+}
+export declare function commandArgv(request: Request, policy?: Policy): string[];
+export declare class AvmClient {
+    private readonly transport;
+    private readonly policy;
+    constructor(transport: Transport, options?: {
+        policy?: Policy;
+        timeoutMs?: number;
+    });
+    private readonly timeoutMs;
+    request(request: Request, options?: {
+        signal?: AbortSignal;
+    }): Promise<Json>;
+}
+/** Executes host-owned AVM remotely: operator JSON stdin or paired, quoted ForceCommand protocol. */
+export declare class SshTransport implements Transport {
+    private readonly target;
+    private readonly mode;
+    private readonly identityFile?;
+    private readonly identityTokenFile?;
+    private readonly command;
+    private readonly maxOutputBytes;
+    constructor(options: {
+        target: string;
+        mode?: "operator" | "paired";
+        identityFile?: string;
+        identityTokenFile?: string;
+        sudo?: boolean;
+        maxOutputBytes?: number;
+    });
+    run(argv: readonly string[], { signal }: {
+        signal: AbortSignal;
+    }): Promise<TransportResult>;
+}