@arcadeai/hypotenuse 0.16.1 → 0.17.0

package/dist/hypotenuse.js

@@ -343,7 +343,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@arcadeai/hypotenuse",
-  version: "0.16.1",
+  version: "0.17.0",
   description: "Hypotenuse \u2014 run coding agents on your machine for Linear agent sessions",
   type: "module",
   license: "Apache-2.0",
@@ -2137,6 +2137,9 @@ function expandPath(raw, baseDir, env = process.env) {
   value = value.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, braced, bare) => env[braced ?? bare] ?? "");
   return isAbsolute(value) ? resolve(value) : resolve(baseDir, value);
 }
+function isRemoteSource(source) {
+  return /^https?:\/\//i.test(source.trim());
+}
 function tildify(path, env = process.env) {
   const home = homeOf(env);
   return path === home ? "~" : path.startsWith(`${home}/`) ? `~/${path.slice(home.length + 1)}` : path;
@@ -2201,6 +2204,9 @@ function machineContext(baseDir, env = process.env) {
 }
 function buildConfigSchema(ctx) {
   const path = () => z9.string().trim().min(1).transform((value) => expandPath(value, ctx.baseDir, ctx.env));
+  const source = () => z9.string().trim().min(1).refine((value) => !isRemoteSource(value) || URL.canParse(value), {
+    message: "expected a path or an http(s) URL"
+  }).transform((value) => isRemoteSource(value) ? value : expandPath(value, ctx.baseDir, ctx.env));
   const duration = () => z9.string().regex(DURATION_PATTERN, "expected a duration such as 45s, 10m, 2h, or 7d").transform(parseDuration);
   const size = () => z9.string().regex(SIZE_PATTERN, "expected a size such as 500MB or 2GB").transform(parseSize);
   const parallel = () => z9.number().int().min(1).max(32);
@@ -2223,7 +2229,8 @@ function buildConfigSchema(ctx) {
   const role = (fallbackPolicy) => z9.strictObject({
     agent: z9.string().trim().min(1).describe("An [agents.<id>] id or a preset name"),
     prompt: z9.string().min(1).optional().describe("The role's entry prompt template, inline"),
-    prompt_file: path().optional().describe("A Markdown prompt template file"),
+    prompt_file: source().optional().describe("A Markdown prompt template file, or a URL of instructions the agent reads with its own tools"),
+    docs: z9.array(source()).default([]).describe("Documents added to the role's instructions: a file's text is included, a URL is linked for the agent to read with its own tools"),
     permission_policy: permissionPolicy(fallbackPolicy),
     max_parallel: parallel().optional().describe("Jobs of this role at once"),
     mode: z9.string().trim().min(1).optional().describe("The ACP session mode to select"),
@@ -3315,7 +3322,7 @@ function validateMachine(config, machine, options = {}) {
   ]) {
     if (!table)
       continue;
-    if (table.prompt_file !== undefined) {
+    if (table.prompt_file !== undefined && !isRemoteSource(table.prompt_file)) {
       const text = machine.readFile(table.prompt_file);
       if (text === null) {
         errors.push({
@@ -3326,6 +3333,14 @@ function validateMachine(config, machine, options = {}) {
         checkTemplate(`roles.${role}.prompt_file`, text, errors);
       }
     }
+    table.docs.forEach((doc, index) => {
+      if (isRemoteSource(doc) || machine.readFile(doc) !== null)
+        return;
+      errors.push({
+        path: `roles.${role}.docs[${index}]`,
+        message: `${home(doc)} cannot be read`
+      });
+    });
     table.extra_mcp_servers.forEach((server, index) => {
       const at = `roles.${role}.extra_mcp_servers[${index}]`;
       for (const [key, name] of [
@@ -6209,6 +6224,26 @@ function fenceFor(text) {
   const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((m) => m[0].length));
   return "`".repeat(Math.max(3, longest + 1));
 }
+function remoteInstructions(url) {
+  return `Your instructions for this role are the document at ${url}. Read it with your tools before doing anything else, and follow it. If you cannot read it, say so in your response and stop.`;
+}
+function roleDocsSection(docs) {
+  if (docs.length === 0)
+    return "";
+  const links = docs.filter((d) => d.text === null).map((d) => d.source);
+  const files = docs.filter((d) => d.text !== null);
+  return [
+    "These documents are part of your instructions: they say how this team works. Where one disagrees with the instructions above about your tools or what you never do, the instructions above win.",
+    links.length ? `Read each of these with your tools before you begin. If one cannot be read, say so in your response.
+${links.map((l) => `- ${l}`).join(`
+`)}` : null,
+    ...files.map((d) => `<doc source=${attr(d.source)}>
+${(d.text ?? "").trim()}
+</doc>`)
+  ].filter(Boolean).join(`
+
+`);
+}
 function reviewSection(review) {
   const issue = review.childIssueIdentifier ?? "the dispatched issue";
   const body = [
@@ -6315,7 +6350,8 @@ ${g.body.trim()}
 `);
   const text = [
     section("hypotenuse", `You are working as the ${assignment.role} agent for ${who}${creator ? ` on behalf of ${creator}` : ""}, in a Linear agent session. You are an AI agent; never claim to be a person. What you say at the end of your turn is posted to the session as your response.${dispatchedBy(assignment)}`),
-    section("role-instructions", renderTemplate(template, values, onUnknown)),
+    section("role-instructions", ctx.templateUrl ? remoteInstructions(ctx.templateUrl) : renderTemplate(template, values, onUnknown)),
+    section("role-docs", roleDocsSection(ctx.docs ?? [])),
     section("linear-context", assignment.promptContext),
     section("guidance", guidance),
     section("conversation", conversation(assignment)),
@@ -6908,11 +6944,29 @@ class Turn {
     const conn = this.conn;
     const sessionId = this.acpSessionId;
     let templateText = null;
-    if (this.role?.prompt_file) {
-      try {
-        templateText = readFileSync7(this.role.prompt_file, "utf8");
-      } catch (error) {
-        throw new TurnFailure(`Runner ${ctx.runnerName} cannot read its ${ctx.assignment.role} prompt file: ${errorMessage(error)}`);
+    let templateUrl = null;
+    const docs = [];
+    if (!this.resumed) {
+      const promptFile = this.role?.prompt_file;
+      if (promptFile && isRemoteSource(promptFile))
+        templateUrl = promptFile;
+      else if (promptFile) {
+        try {
+          templateText = readFileSync7(promptFile, "utf8");
+        } catch (error) {
+          throw new TurnFailure(`Runner ${ctx.runnerName} cannot read its ${ctx.assignment.role} prompt file: ${errorMessage(error)}`);
+        }
+      }
+      for (const doc of this.role?.docs ?? []) {
+        if (isRemoteSource(doc)) {
+          docs.push({ source: doc, text: null });
+          continue;
+        }
+        try {
+          docs.push({ source: tildify(doc), text: readFileSync7(doc, "utf8") });
+        } catch (error) {
+          throw new TurnFailure(`Runner ${ctx.runnerName} cannot read a ${ctx.assignment.role} doc: ${errorMessage(error)}`);
+        }
       }
     }
     const blocks = buildPrompt(ctx.assignment, this.role, {
@@ -6922,6 +6976,8 @@ class Turn {
       runnerName: ctx.runnerName,
       resumed: this.resumed,
       templateText,
+      templateUrl,
+      docs,
       readOnly: this.workspace?.mode === "readonly"
     }, (name) => ctx.log.warn(`the prompt template uses an unknown variable {{${name}}}; it rendered empty`));
     this.promptStartedAt = this.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcadeai/hypotenuse",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Hypotenuse — run coding agents on your machine for Linear agent sessions",
   "type": "module",
   "license": "Apache-2.0",