@opengeni/runtime 2.5.3-canary.0 → 2.5.3-canary.2

package/src/sandbox/selfhosted/session.ts

@@ -31,6 +31,11 @@ import {
   type StreamChannel,
 } from "@opengeni/agent-proto";
 import { DESKTOP_STREAM_PORT } from "@opengeni/contracts";
+import {
+  SELFHOSTED_FILE_CHUNK_BYTES,
+  fileContentDigest,
+  transferEditorFile,
+} from "./file-transfer";
 // `Manifest` from the ALLOWED sandbox-leaf entrypoint (`@openai/agents/sandbox`
 // re-exports `@openai/agents-core/sandbox`, which exports the Manifest class) —
 // NOT the agent-loop `@openai/agents` root the sandbox leaf forbids. The live
@@ -262,6 +267,7 @@ export interface SelfhostedBackgroundCommandAdoption {
 /** Exact command-admission snapshot. A worker resolves this immediately before
  * every exec/Git admission; retries and already-started operations retain it. */
 export interface SelfhostedOperationAdmission {
+  transactionalFsWriteSupported?: boolean;
   /** Workspace segment of the physical agent/relay route. Personal machines may
    * originate in a different same-organization workspace than the session. */
   workspaceId?: string;
@@ -284,6 +290,8 @@ export interface SelfhostedOperationAdmission {
 }
 
 export interface SelfhostedSessionDeps {
+  /** Exact live daemon capability; absent preserves legacy small-file writes. */
+  transactionalFsWriteSupported?: boolean;
   /** Authorization/session workspace. */
   workspaceId: string;
   /** Physical control-plane workspace. Defaults to workspaceId for legacy and
@@ -488,6 +496,7 @@ export class SelfhostedSession {
   private readonly resourcePolicy: OperationResourcePolicy | undefined;
   private readonly resourcePolicySupported: boolean;
   private readonly operationCpuQuotaSupported: boolean;
+  private readonly transactionalFsWriteSupported: boolean;
   private readonly defaultOpStream: SelfhostedOpStreamDeps | undefined;
   private readonly connectionInstanceId: string;
   private readonly resolveOperationAdmission:
@@ -560,6 +569,7 @@ export class SelfhostedSession {
     this.resourcePolicy = normalizeOperationResourcePolicy(deps.operationResourcePolicy);
     this.resourcePolicySupported = deps.operationResourcePolicySupported === true;
     this.operationCpuQuotaSupported = deps.operationCpuQuotaSupported === true;
+    this.transactionalFsWriteSupported = deps.transactionalFsWriteSupported === true;
     this.defaultOpStream = deps.opStream;
     this.connectionInstanceId = deps.connectionInstanceId;
     this.resolveOperationAdmission = deps.resolveOperationAdmission;
@@ -577,6 +587,7 @@ export class SelfhostedSession {
             subject: this.subject,
             resourcePolicy: this.resourcePolicy,
             opStream: deps.opStream,
+            transactionalFsWriteSupported: this.transactionalFsWriteSupported,
           })
         : undefined;
     // A valid Manifest whose root is the machine's actual effective root. There
@@ -644,6 +655,7 @@ export class SelfhostedSession {
   }
 
   private async admitOperation(commandPolicy: boolean): Promise<{
+    transactionalFsWriteSupported: boolean;
     controlWorkspaceId: string;
     connectionInstanceId: string;
     subject: string;
@@ -664,6 +676,7 @@ export class SelfhostedSession {
         subject: this.subject,
         resourcePolicy: commandPolicy ? this.resourcePolicy : undefined,
         opStream: this.defaultOpStream,
+        transactionalFsWriteSupported: this.transactionalFsWriteSupported,
       };
     }
 
@@ -698,6 +711,7 @@ export class SelfhostedSession {
       ),
       resourcePolicy: commandPolicy ? resourcePolicy : undefined,
       opStream: resolved.opStream,
+      transactionalFsWriteSupported: resolved.transactionalFsWriteSupported === true,
     };
   }
 
@@ -879,7 +893,9 @@ export class SelfhostedSession {
           machineId: this.agentId,
           faultClass: selfhostedFaultClass(error),
           // Known only on a PAYLOAD_TOO_LARGE fault (the agent's encoded_bytes detail).
-          ...(Number.isFinite(encoded) ? { replyBytes: encoded } : {}),
+          ...(Number.isFinite(encoded) && error.detail.direction !== "request"
+            ? { replyBytes: encoded }
+            : {}),
         });
         // Fold the retry count into the DRAINING copy when we actually retried, so
         // the surfaced message reads "…retried N times first…".
@@ -1324,8 +1340,169 @@ export class SelfhostedSession {
     const pathExists = (path: string): Promise<boolean> => this.pathExists(path, runAs);
     const readText = async (path: string): Promise<string> =>
       decoder.decode(await this.readFile({ path, ...(runAs ? { runAs } : {}) }));
-    const writeText = async (path: string, content: string): Promise<void> => {
-      await this.writeFile({ path, content, createParents: true });
+    const writeText = async (
+      path: string,
+      content: string,
+      base?: string | (() => Promise<string | undefined>),
+    ): Promise<((source: string, sourceBase: string) => Promise<void>) | undefined> => {
+      const bytes = encoder.encode(content);
+      if (bytes.byteLength <= SELFHOSTED_FILE_CHUNK_BYTES) {
+        await this.writeFile({ path, content, createParents: true });
+        return;
+      }
+      const initial = await this.admitOperation(false);
+      if (!initial.transactionalFsWriteSupported) {
+        // Older agents may have a larger negotiated message budget. Preserve
+        // their existing writes; a real size rejection remains a typed fault.
+        await this.writeFile({ path, content, createParents: true });
+        return;
+      }
+      if (runAs) {
+        throw new SelfhostedControlError({
+          code: ErrorCode.ERROR_CODE_UNSUPPORTED,
+          message:
+            "Transactional file editing does not support runAs impersonation; no file was written.",
+          reason: null,
+          retryable: false,
+        });
+      }
+      const requestTransfer = async (
+        requestId: string,
+        op: NonNullable<ControlRequest["op"]>,
+      ): Promise<ControlResponse> => {
+        const startedAt = Date.now();
+        try {
+          const current = await this.admitOperation(false);
+          if (
+            !current.transactionalFsWriteSupported ||
+            current.subject !== initial.subject ||
+            current.connectionInstanceId !== initial.connectionInstanceId
+          ) {
+            throw new Error(
+              "The authorized machine connection changed during the file transfer; the operation was not replayed.",
+            );
+          }
+          const response = await this.controlRpc.request(
+            current.subject,
+            {
+              requestId,
+              epoch: this.epoch,
+              op,
+              resourcePolicy: undefined,
+            },
+            { timeoutMs: this.timeoutMs },
+          );
+          if (response.requestId !== requestId)
+            throw new Error("The machine returned a mismatched file-transfer response identity.");
+          const error = response.error
+            ? agentErrorToControlError(response.error, requestId)
+            : undefined;
+          this.emitOp({
+            op: op.$case,
+            outcome: error || !response.result ? "failed" : "ok",
+            healed: false,
+            retries: 0,
+            durationMs: Date.now() - startedAt,
+            machineId: this.agentId,
+            ...(error
+              ? { code: error.code, reason: error.reason, faultClass: selfhostedFaultClass(error) }
+              : {}),
+          });
+          return response;
+        } catch (error) {
+          this.emitOp({
+            op: op.$case,
+            outcome: "failed",
+            healed: false,
+            retries: 0,
+            durationMs: Date.now() - startedAt,
+            machineId: this.agentId,
+            ...(error instanceof SelfhostedControlError
+              ? { code: error.code, reason: error.reason, faultClass: selfhostedFaultClass(error) }
+              : {}),
+          });
+          throw error;
+        }
+      };
+      const resolvedBase = typeof base === "function" ? await base() : base;
+      const transferStartedAt = Date.now();
+      try {
+        const result = await transferEditorFile({
+          path: resolveConnectedMachinePath(this.workspaceRoot, path),
+          content: bytes,
+          ...(resolvedBase === undefined ? {} : { baseContent: encoder.encode(resolvedBase) }),
+          request: requestTransfer,
+        });
+        // Unlike physical request observations, this is a verified file outcome.
+        this.emitOp({
+          op: "fsWrite",
+          outcome: "ok",
+          healed: result.recovered,
+          retries: 0,
+          durationMs: Date.now() - transferStartedAt,
+          machineId: this.agentId,
+        });
+      } catch (error) {
+        this.emitOp({
+          op: "fsWrite",
+          outcome: "failed",
+          healed: false,
+          retries: 0,
+          durationMs: Date.now() - transferStartedAt,
+          machineId: this.agentId,
+        });
+        throw error;
+      }
+      return async (source, sourceBase) => {
+        // A move is verified destination replacement followed by source cleanup,
+        // not an atomic rename. Never retarget cleanup after a runner change.
+        // The source check and deletion are not CAS against unrelated writers.
+        try {
+          const sourcePath = resolveConnectedMachinePath(this.workspaceRoot, source);
+          const sourceBytes: Uint8Array[] = [];
+          let offset = 0;
+          let total = Infinity;
+          while (offset < total) {
+            const reply = await requestTransfer(crypto.randomUUID(), {
+              $case: "fsRead",
+              fsRead: {
+                path: sourcePath,
+                offset: String(offset),
+                length: String(SELFHOSTED_FILE_CHUNK_BYTES),
+              },
+            });
+            if (reply.error) throw agentErrorToControlError(reply.error);
+            if (reply.result?.$case !== "fsRead")
+              throw new Error("Source verification response missing");
+            const part = reply.result.fsRead;
+            total = safeWireSize(part.totalSize, "source file size");
+            if (!part.content.length && offset < total)
+              throw new Error("Source verification was incomplete");
+            sourceBytes.push(part.content);
+            offset += part.content.length;
+          }
+          const actual = new Uint8Array(offset);
+          let cursor = 0;
+          for (const chunk of sourceBytes) {
+            actual.set(chunk, cursor);
+            cursor += chunk.length;
+          }
+          if (fileContentDigest(actual) !== fileContentDigest(encoder.encode(sourceBase)))
+            throw new Error("Source changed before move cleanup");
+          const reply = await requestTransfer(crypto.randomUUID(), {
+            $case: "fsRemove",
+            fsRemove: { path: sourcePath, recursive: false },
+          });
+          if (reply.error) throw agentErrorToControlError(reply.error);
+          if (reply.result?.$case !== "fsRemove")
+            throw new Error("Source cleanup response missing");
+        } catch (cause) {
+          throw new Error(
+            "The destination edit was verified, but source cleanup was not verified. The move was not replayed; inspect both paths.",
+            { cause },
+          );
+        }
+      };
     };
     const deletePath = async (path: string): Promise<void> => {
       const result = await this.call({
@@ -1351,9 +1528,15 @@ export class SelfhostedSession {
         const current = await readText(operation.path);
         const next = applyDiff(current, operation.diff);
         const destination = operation.moveTo ?? operation.path;
-        await writeText(destination, next);
+        const destinationBase =
+          destination === operation.path
+            ? current
+            : async () =>
+                (await pathExists(destination)) ? await readText(destination) : undefined;
+        const cleanup = await writeText(destination, next, destinationBase);
         if (operation.moveTo && destination !== operation.path) {
-          await deletePath(operation.path);
+          if (cleanup) await cleanup(operation.path, current);
+          else await deletePath(operation.path);
         }
         return {};
       },
@@ -1708,6 +1891,7 @@ export class SelfhostedSandboxClient {
   private readonly operationResourcePolicy: SelfhostedOperationResourcePolicy | undefined;
   private readonly operationResourcePolicySupported: boolean | undefined;
   private readonly operationCpuQuotaSupported: boolean | undefined;
+  private readonly transactionalFsWriteSupported: boolean | undefined;
   private readonly resolveOperationAdmission:
     | (() => Promise<SelfhostedOperationAdmission | null>)
     | undefined;
@@ -1748,6 +1932,7 @@ export class SelfhostedSandboxClient {
     operationResourcePolicy?: SelfhostedOperationResourcePolicy;
     operationResourcePolicySupported?: boolean;
     operationCpuQuotaSupported?: boolean;
+    transactionalFsWriteSupported?: boolean;
     resolveOperationAdmission?: () => Promise<SelfhostedOperationAdmission | null>;
     adoptBackgroundCommand?: SelfhostedSessionDeps["adoptBackgroundCommand"];
     settleBackgroundCommand?: SelfhostedSessionDeps["settleBackgroundCommand"];
@@ -1779,6 +1964,7 @@ export class SelfhostedSandboxClient {
     this.operationResourcePolicy = opts.operationResourcePolicy;
     this.operationResourcePolicySupported = opts.operationResourcePolicySupported;
     this.operationCpuQuotaSupported = opts.operationCpuQuotaSupported;
+    this.transactionalFsWriteSupported = opts.transactionalFsWriteSupported;
     this.resolveOperationAdmission = opts.resolveOperationAdmission;
     this.adoptBackgroundCommand = opts.adoptBackgroundCommand;
     this.settleBackgroundCommand = opts.settleBackgroundCommand;
@@ -1822,6 +2008,7 @@ export class SelfhostedSandboxClient {
       ...(this.operationCpuQuotaSupported !== undefined
         ? { operationCpuQuotaSupported: this.operationCpuQuotaSupported }
         : {}),
+      transactionalFsWriteSupported: this.transactionalFsWriteSupported === true,
       ...(this.resolveOperationAdmission !== undefined
         ? { resolveOperationAdmission: this.resolveOperationAdmission }
         : {}),
@@ -1941,6 +2128,7 @@ export interface SelfhostedSessionBuild {
   operationResourcePolicySupported?: boolean;
   /** Exact live CPU enforcement capability paired with the initial snapshot. */
   operationCpuQuotaSupported?: boolean;
+  transactionalFsWriteSupported?: boolean;
   /** Live last-boundary operation admission resolver; see SelfhostedSessionDeps. */
   resolveOperationAdmission?: () => Promise<SelfhostedOperationAdmission | null>;
   adoptBackgroundCommand?: SelfhostedSessionDeps["adoptBackgroundCommand"];
@@ -1996,6 +2184,7 @@ export async function buildSelfhostedBackendSession(
     ...(deps.operationCpuQuotaSupported !== undefined
       ? { operationCpuQuotaSupported: deps.operationCpuQuotaSupported }
       : {}),
+    transactionalFsWriteSupported: deps.transactionalFsWriteSupported === true,
     ...(deps.resolveOperationAdmission !== undefined
       ? { resolveOperationAdmission: deps.resolveOperationAdmission }
       : {}),

package/src/workspace-skills.ts

@@ -1,4 +1,16 @@
 import { createHash } from "node:crypto";
+import { tool, type Tool } from "@openai/agents";
+import { parseSkillFrontmatter } from "@opengeni/contracts";
+import { z } from "zod";
+import {
+  assertSkillRelativePath,
+  listSkillPaths,
+  readSkillFiles,
+  SkillFileError,
+  SKILL_READ_MAX_PATHS,
+  SKILL_READ_MAX_OUTPUT_BYTES,
+  type SkillTextFile,
+} from "./skill-files";
 
 import {
   Capability,
@@ -64,24 +76,94 @@ export class WorkspaceSkillsCapability extends Capability {
     super();
   }
 
-  override async instructions(): Promise<string | null> {
+  override bind(session: SandboxSessionLike): this {
+    if (this._session !== session) delete this.discovery;
+    return super.bind(session);
+  }
+
+  private discover(): Promise<readonly WorkspaceSkill[]> {
     const session = requireWorkspaceSkillSession(this._session);
-    this.discovery ??= discoverWorkspaceSkills(
+    return (this.discovery ??= discoverWorkspaceSkills(
       session,
       this.searchPaths,
       this.reservedNames,
       this._runAs,
       this.shadowedNames,
-    );
-    const skills = await this.discovery;
+    ));
+  }
+
+  override tools(): Tool<unknown>[] {
+    return [
+      tool({
+        name: "repository_skill_read",
+        description:
+          "Read current repository Skill files from the bound workspace. Use the exact repository: identifier from the Repository skills index. Omit paths for SKILL.md; explicit relative paths read only those files. Set listFiles:true without paths for a bounded file inventory. This reads live files through the sandbox, including Connected Machines.",
+        parameters: z.object({
+          skill: z.string().min(1),
+          paths: z.array(z.string().min(1).max(1024)).min(1).max(SKILL_READ_MAX_PATHS).optional(),
+          listFiles: z.boolean().optional(),
+        }),
+        execute: async (request) => {
+          if (request.listFiles && request.paths !== undefined)
+            throw new SkillFileError(
+              "invalid_request",
+              "listFiles:true cannot be combined with paths.",
+            );
+          const skill = (await this.discover()).find(
+            (entry) => repositorySkillId(entry) === request.skill,
+          );
+          if (!skill)
+            throw new SkillFileError(
+              "missing_file",
+              "Repository Skill is not in this index. Use its exact repository: identifier.",
+            );
+          const session = requireWorkspaceSkillSession(this._session);
+          const root = skill.path.slice(0, -SKILL_FILE.length - 1);
+          const result = request.listFiles
+            ? listSkillPaths(
+                await repositorySkillInventory(session, root, this._runAs),
+                MAX_SKILL_ENTRIES,
+              )
+            : readSkillFiles(
+                await repositorySkillFiles(
+                  session,
+                  root,
+                  request.paths ?? [SKILL_FILE],
+                  this._runAs,
+                ),
+                request.paths,
+              );
+          const output = JSON.stringify({
+            skillId: request.skill,
+            source: "repository",
+            root,
+            ...result,
+          });
+          if (new TextEncoder().encode(output).byteLength > SKILL_READ_MAX_OUTPUT_BYTES) {
+            throw new SkillFileError(
+              "output_too_large",
+              "Repository Skill response exceeds the read output limit. Request fewer paths.",
+            );
+          }
+          return output;
+        },
+      }),
+    ];
+  }
+
+  override async instructions(): Promise<string | null> {
+    const skills = await this.discover();
     if (skills.length === 0) return null;
 
     const available = skills
-      .map((skill) => `- ${skill.name}: ${skill.description} (file: ${skill.path})`)
+      .map(
+        (skill) =>
+          `- ${JSON.stringify({ id: repositorySkillId(skill), name: skill.name, description: skill.description, reader: "repository_skill_read", path: skill.path })}`,
+      )
       .join("\n");
     return `## Repository skills
 
-Repository skills are instructions already present in the live workspace. They do not need to be loaded or copied.
+Repository skills are instructions already present in the live workspace. Read them with repository_skill_read using the exact repository: id below. The reader returns current live files; ordinary filesystem tools execute referenced scripts and read binary assets. Configured Skills use their separate skill_read index.
 
 ### Available repository skills
 ${available}
@@ -165,6 +247,18 @@ async function discoverWorkspaceSkillsUnmeasured(
       const skillMarkdownPath = joinWorkspacePath(entry.path, SKILL_FILE);
       let markdown: string;
       try {
+        // Match reader/inventory eligibility: symlink entrypoints are not
+        // advertised because the portable filesystem API cannot prove containment.
+        const skillEntries = await session.listDir({
+          path: entry.path,
+          ...(runAs ? { runAs } : {}),
+        });
+        if (
+          !skillEntries.some(
+            (candidate) => candidate.name === SKILL_FILE && candidate.type === "file",
+          )
+        )
+          continue;
         const content = await session.readFile({
           path: skillMarkdownPath,
           ...(runAs ? { runAs } : {}),
@@ -182,7 +276,7 @@ async function discoverWorkspaceSkillsUnmeasured(
       const key = name.toLowerCase();
       if (shadowedNames.has(key)) continue;
       const description = frontmatter.description?.trim() || "No description provided.";
-      if (description.length > 2_048 || /[\r\n]/.test(description)) {
+      if (description.length > 2_048) {
         throw new Error(`Repository skill "${name}" has an invalid description`);
       }
       if (reservedNames.has(key)) {
@@ -267,34 +361,80 @@ async function fingerprintWorkspaceDirectory(
   return hash.digest("hex");
 }
 
-function parseSkillFrontmatter(markdown: string): {
-  name?: string;
-  description?: string;
-} {
-  const lines = markdown.split(/\r?\n/);
-  if (lines[0]?.trim() !== "---") return {};
-  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
-  if (end === -1) return {};
-  const values: Record<string, string> = {};
-  for (const line of lines.slice(1, end)) {
-    const separator = line.indexOf(":");
-    if (separator === -1) continue;
-    const key = line.slice(0, separator).trim();
-    if (key !== "name" && key !== "description") continue;
-    values[key] = unquote(line.slice(separator + 1).trim());
+function repositorySkillId(skill: WorkspaceSkill): string {
+  return `repository:${skill.path}`;
+}
+
+/** Resolve only ordinary directory entries under the discovered Skill root.
+ * Never treat a caller identifier as a path or follow a listed symlink. The
+ * bound sandbox remains the filesystem authority, including concurrent edits.
+ */
+async function repositorySkillFiles(
+  session: SandboxSessionLike,
+  root: string,
+  paths: readonly string[],
+  runAs?: string,
+): Promise<SkillTextFile[]> {
+  // Validate the entire request before touching the filesystem.
+  readSkillFiles(
+    paths.map((path) => ({ path, content: "" })),
+    paths,
+  );
+  const files: SkillTextFile[] = [];
+  for (const path of paths) {
+    let directory = root;
+    const segments = path.split("/");
+    for (const [index, name] of segments.entries()) {
+      const entries = await session.listDir!({ path: directory, ...(runAs ? { runAs } : {}) });
+      const entry = entries.find((candidate) => candidate.name === name);
+      const expected = index === segments.length - 1 ? "file" : "dir";
+      if (entry?.type !== expected)
+        throw new SkillFileError("missing_file", `Repository Skill file is unavailable: ${path}`);
+      directory = joinWorkspacePath(directory, name);
+    }
+    const content = await session.readFile!({ path: directory, ...(runAs ? { runAs } : {}) });
+    files.push({
+      path,
+      content:
+        typeof content === "string"
+          ? content
+          : new TextDecoder("utf-8", { fatal: true }).decode(content),
+    });
+    // Bound aggregate output as each file arrives; do not truncate accepted text.
+    readSkillFiles(
+      files,
+      files.map((file) => file.path),
+    );
   }
-  return values;
+  return files;
 }
 
-function unquote(value: string): string {
-  if (
-    value.length >= 2 &&
-    value[0] === value[value.length - 1] &&
-    (value[0] === '"' || value[0] === "'")
-  ) {
-    return value.slice(1, -1);
+async function repositorySkillInventory(
+  session: SandboxSessionLike,
+  root: string,
+  runAs?: string,
+): Promise<SkillTextFile[]> {
+  const files: SkillTextFile[] = [];
+  let count = 0;
+  async function visit(relative: string): Promise<void> {
+    const entries = await session.listDir!({
+      path: relative ? joinWorkspacePath(root, relative) : root,
+      ...(runAs ? { runAs } : {}),
+    });
+    for (const entry of entries) {
+      if (++count > MAX_SKILL_ENTRIES)
+        throw new SkillFileError("output_too_large", "Repository Skill inventory is too large.");
+      // Paths derive from validated names, never provider-returned absolute paths.
+      assertSkillRelativePath(entry.name);
+      if (entry.name.includes("/"))
+        throw new SkillFileError("invalid_path", "Invalid repository directory entry.");
+      const path = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.type === "dir") await visit(path);
+      else if (entry.type === "file") files.push({ path, content: "" });
+    }
   }
-  return value;
+  await visit("");
+  return files;
 }
 
 function joinWorkspacePath(parent: string, child: string): string {