refactor(agent-runtime): tseng skills + result types + protected trpc

- Layered skills/ module: domain (skill-name/path, frontmatter,
  branch-timestamp), infra ports (github-rest, git-protocol,
  local-skill-repo), services (install/scan/publish + facade),
  compose.ts + index.ts
- Contract: skills router on protectedProcedure; errorFormatter
  lifts upstream envelope to data.upstream
- Files module migrated to Result<T, FilesDomainError> + protected
- server.ts: per-request createContext reads bearer; deletes hand-
  rolled /api/skills/* HTTP routes
- api-server: typed @trpc/client to agent-runtime; instance proxy
  swaps user JWT for agent bearer after ownership check
- Drop skills/files unit tests (per spec deferral)
- tseng vocabulary: Skills bounded context; adoption.md notes Result
  applied for agent-runtime

Signed-off-by: Tomas Weiss <tomas.weiss2@gmail.com>

Author: tomkis

packages/agent-runtime-api/src/context.ts

@@ -1,5 +1,12 @@
 import type { FilesService } from "./modules/files/types.js";
+import type { SkillsService } from "./modules/skills/types.js";
+
+export interface AgentAuth {
+  agentCaller: true;
+}
 
 export interface AgentRuntimeContext {
+  auth: AgentAuth | null;
   files: FilesService;
+  skills: SkillsService;
 }

packages/agent-runtime-api/src/index.ts

@@ -1,3 +1,27 @@
 export type { AppRouter } from "./router.js";
-export type { AgentRuntimeContext } from "./context.js";
-export type { FilesService } from "./modules/files/types.js";
+export type { AgentAuth, AgentRuntimeContext } from "./context.js";
+export type { Result } from "./result.js";
+export { ok, err } from "./result.js";
+export type {
+  FileReadResult,
+  FileWriteOk,
+  FilesDomainError,
+  FilesService,
+} from "./modules/files/types.js";
+export type {
+  GitHubErrorBody,
+  InstallSkillInput,
+  InstallSkillResult,
+  ListLocalSkillsInput,
+  LocalSkill,
+  LocalSkillFile,
+  PublishSkillInput,
+  PublishSkillResult,
+  ReadLocalSkillInput,
+  ReadLocalSkillResult,
+  ScanSkillSourceInput,
+  ScannedSkill,
+  SkillsDomainError,
+  SkillsService,
+  UninstallSkillInput,
+} from "./modules/skills/types.js";

packages/agent-runtime-api/src/modules/files/router.ts

@@ -1,113 +1,95 @@
 import { TRPCError } from "@trpc/server";
 import { z } from "zod";
-import { t } from "../../trpc.js";
+import { protectedProcedure, t } from "../../trpc.js";
+import type { FilesDomainError } from "./types.js";
 
 const pathSchema = z.string().min(1);
 
+function toTrpcError(error: FilesDomainError): TRPCError {
+  switch (error.kind) {
+    case "Forbidden":
+      return new TRPCError({ code: "FORBIDDEN", message: error.reason });
+    case "NotFound":
+      return new TRPCError({ code: "NOT_FOUND" });
+    case "Conflict":
+      return new TRPCError({
+        code: "CONFLICT",
+        message: "file changed on disk",
+        cause: { currentMtimeMs: error.currentMtimeMs },
+      });
+    case "AlreadyExists":
+      return new TRPCError({ code: "CONFLICT", message: "path already exists" });
+    case "PayloadTooLarge":
+      return new TRPCError({ code: "PAYLOAD_TOO_LARGE", message: error.detail });
+  }
+}
+
 export const filesRouter = t.router({
-  tree: t.procedure.query(({ ctx }) => ({
+  tree: protectedProcedure.query(({ ctx }) => ({
     entries: ctx.files.buildTree(),
   })),
 
-  read: t.procedure
+  read: protectedProcedure
     .input(z.object({ path: pathSchema }))
     .query(async ({ ctx, input }) => {
       const result = await ctx.files.readFileSafe(input.path);
-      if (!result) {
-        throw new TRPCError({ code: "NOT_FOUND" });
-      }
-      return result;
+      if (!result.ok) throw toTrpcError(result.error);
+      return result.value;
     }),
 
-  write: t.procedure
+  write: protectedProcedure
     .input(z.object({
       path: pathSchema,
       content: z.string(),
       expectedMtimeMs: z.number().optional(),
     }))
     .mutation(async ({ ctx, input }) => {
-      try {
-        const result = await ctx.files.writeFileSafe(
-          input.path,
-          input.content,
-          input.expectedMtimeMs,
-        );
-        if ("conflict" in result) {
-          throw new TRPCError({
-            code: "CONFLICT",
-            message: "file changed on disk",
-            cause: { currentMtimeMs: result.currentMtimeMs },
-          });
-        }
-        return { mtimeMs: result.mtimeMs };
-      } catch (err) {
-        if (err instanceof TRPCError) throw err;
-        throw new TRPCError({ code: "FORBIDDEN", message: (err as Error).message });
-      }
+      const result = await ctx.files.writeFileSafe(
+        input.path,
+        input.content,
+        input.expectedMtimeMs,
+      );
+      if (!result.ok) throw toTrpcError(result.error);
+      return { mtimeMs: result.value.mtimeMs };
     }),
 
-  create: t.procedure
+  create: protectedProcedure
     .input(z.object({ path: pathSchema, content: z.string() }))
     .mutation(async ({ ctx, input }) => {
-      try {
-        const result = await ctx.files.createFileSafe(input.path, input.content);
-        if ("exists" in result) {
-          throw new TRPCError({ code: "CONFLICT", message: "path already exists" });
-        }
-        return { mtimeMs: result.mtimeMs };
-      } catch (err) {
-        if (err instanceof TRPCError) throw err;
-        throw new TRPCError({ code: "FORBIDDEN", message: (err as Error).message });
-      }
+      const result = await ctx.files.createFileSafe(input.path, input.content);
+      if (!result.ok) throw toTrpcError(result.error);
+      return { mtimeMs: result.value.mtimeMs };
     }),
 
-  mkdir: t.procedure
+  mkdir: protectedProcedure
     .input(z.object({ path: pathSchema }))
     .mutation(async ({ ctx, input }) => {
-      try {
-        const result = await ctx.files.mkdirSafe(input.path);
-        if ("exists" in result) {
-          throw new TRPCError({ code: "CONFLICT", message: "path exists and is not a directory" });
-        }
-        return { ok: true as const };
-      } catch (err) {
-        if (err instanceof TRPCError) throw err;
-        throw new TRPCError({ code: "FORBIDDEN", message: (err as Error).message });
-      }
+      const result = await ctx.files.mkdirSafe(input.path);
+      if (!result.ok) throw toTrpcError(result.error);
+      return { ok: true as const };
     }),
 
-  rename: t.procedure
+  rename: protectedProcedure
     .input(z.object({
       from: pathSchema,
       to: pathSchema,
       overwrite: z.boolean().optional(),
     }))
     .mutation(async ({ ctx, input }) => {
-      try {
-        const result = await ctx.files.renameSafe(input.from, input.to, input.overwrite ?? false);
-        if ("exists" in result) {
-          throw new TRPCError({ code: "CONFLICT", message: "destination already exists" });
-        }
-        return { ok: true as const };
-      } catch (err) {
-        if (err instanceof TRPCError) throw err;
-        throw new TRPCError({ code: "FORBIDDEN", message: (err as Error).message });
-      }
+      const result = await ctx.files.renameSafe(input.from, input.to, input.overwrite ?? false);
+      if (!result.ok) throw toTrpcError(result.error);
+      return { ok: true as const };
     }),
 
-  remove: t.procedure
+  remove: protectedProcedure
     .input(z.object({ path: pathSchema }))
     .mutation(async ({ ctx, input }) => {
-      try {
-        await ctx.files.deleteSafe(input.path);
-        return { ok: true as const };
-      } catch (err) {
-        if (err instanceof TRPCError) throw err;
-        throw new TRPCError({ code: "FORBIDDEN", message: (err as Error).message });
-      }
+      const result = await ctx.files.deleteSafe(input.path);
+      if (!result.ok) throw toTrpcError(result.error);
+      return { ok: true as const };
     }),
 
-  upload: t.procedure
+  upload: protectedProcedure
     .input(z.object({
       path: pathSchema,
       contentBase64: z.string(),
@@ -118,27 +100,16 @@ export const filesRouter = t.router({
       overwrite: z.boolean().optional(),
     }))
     .mutation(async ({ ctx, input }) => {
-      try {
-        const result = await ctx.files.uploadFileSafe(
-          input.path,
-          input.contentBase64,
-          input.overwrite ?? false,
-        );
-        if ("exists" in result) {
-          throw new TRPCError({ code: "CONFLICT", message: "path already exists" });
-        }
-        return {
-          mtimeMs: result.mtimeMs,
-          absolutePath: result.absolutePath,
-          contentType: input.contentType,
-        };
-      } catch (err) {
-        if (err instanceof TRPCError) throw err;
-        const msg = (err as Error).message;
-        throw new TRPCError({
-          code: /too large/i.test(msg) ? "PAYLOAD_TOO_LARGE" : "FORBIDDEN",
-          message: msg,
-        });
-      }
+      const result = await ctx.files.uploadFileSafe(
+        input.path,
+        input.contentBase64,
+        input.overwrite ?? false,
+      );
+      if (!result.ok) throw toTrpcError(result.error);
+      return {
+        mtimeMs: result.value.mtimeMs,
+        absolutePath: result.value.absolutePath,
+        contentType: input.contentType,
+      };
     }),
 });

packages/agent-runtime-api/src/modules/files/types.ts

@@ -1,9 +1,11 @@
+import type { Result } from "../../result.js";
+
 export interface FileReadResult {
   path: string;
-  content?: string;  // UTF-8 for text, base64 for binary
-  binary?: boolean;  // true when content is base64-encoded or file exceeds size limit
-  mimeType?: string; // detected MIME type (absent when file exceeds size limit)
-  mtimeMs?: number;  // mtime at read; absent when file exceeds size limit
+  content?: string;
+  binary?: boolean;
+  mimeType?: string;
+  mtimeMs?: number;
 }
 
 export interface FileWriteOk {
@@ -13,46 +15,41 @@ export interface FileWriteOk {
   absolutePath?: string;
 }
 
-export interface FileConflict {
-  conflict: true;
-  currentMtimeMs: number;
-}
-
-export interface PathExists {
-  exists: true;
-}
+export type FilesDomainError =
+  | { kind: "Forbidden"; reason: string }
+  | { kind: "NotFound"; path: string }
+  | { kind: "Conflict"; currentMtimeMs: number }
+  | { kind: "AlreadyExists"; path: string }
+  | { kind: "PayloadTooLarge"; detail: string };
 
 export interface FilesService {
   buildTree: () => { path: string; type: "file" | "dir" }[];
-  readFileSafe: (rel: string) => Promise<FileReadResult | null>;
-  /** Overwrite an existing file. Returns conflict when expectedMtimeMs is
+  readFileSafe: (rel: string) => Promise<Result<FileReadResult, FilesDomainError>>;
+  /** Overwrite an existing file. Errors with Conflict when expectedMtimeMs is
    *  provided and the file was modified in the meantime. */
   writeFileSafe: (
     rel: string,
     content: string,
     expectedMtimeMs?: number,
-  ) => Promise<FileWriteOk | FileConflict>;
-  /** Create a new file. Fails with `{exists: true}` when the path already
-   *  exists. Auto-creates missing parent directories. */
-  createFileSafe: (rel: string, content: string) => Promise<FileWriteOk | PathExists>;
-  /** Create a directory (recursive mkdir). Returns `{exists: true}` if the
-   *  path already exists and is not a directory. */
-  mkdirSafe: (rel: string) => Promise<{ ok: true } | PathExists>;
-  /** Move/rename a file or directory. Returns `{exists: true}` when the
+  ) => Promise<Result<FileWriteOk, FilesDomainError>>;
+  /** Create a new file. Errors with AlreadyExists when the path is taken.
+   *  Auto-creates missing parent directories. */
+  createFileSafe: (rel: string, content: string) => Promise<Result<FileWriteOk, FilesDomainError>>;
+  /** Create a directory (recursive mkdir). */
+  mkdirSafe: (rel: string) => Promise<Result<{ ok: true }, FilesDomainError>>;
+  /** Move/rename a file or directory. Errors with AlreadyExists when the
    *  destination exists and overwrite is false. */
   renameSafe: (
     from: string,
     to: string,
     overwrite: boolean,
-  ) => Promise<{ ok: true } | PathExists>;
-  /** Remove a file or directory (recursive for dirs). */
-  deleteSafe: (rel: string) => Promise<{ ok: true }>;
-  /** Write a binary payload (base64-encoded) to disk. When `overwrite` is
-   *  false and the destination exists, returns `{exists: true}` without
-   *  clobbering. Intended for UI uploads where the client has no prior mtime. */
+  ) => Promise<Result<{ ok: true }, FilesDomainError>>;
+  deleteSafe: (rel: string) => Promise<Result<{ ok: true }, FilesDomainError>>;
+  /** Write a binary payload (base64-encoded) to disk. Intended for UI
+   *  uploads where the client has no prior mtime. */
   uploadFileSafe: (
     rel: string,
     base64: string,
     overwrite: boolean,
-  ) => Promise<FileWriteOk | PathExists>;
+  ) => Promise<Result<FileWriteOk, FilesDomainError>>;
 }