@asermax/pi-tentacles 1.0.0 → 1.2.0

package/README.md

@@ -29,10 +29,10 @@ The helper reads these where it runs, on your machine. On pi, set them in pi's s
 | `TENTACLES_API_KEY`            | the API key                                 | required           |
 | `TENTACLES_HELPER`             | the helper's path                           | the bundled helper |
 | `TENTACLES_SESSION_PROVIDER`   | the model provider                          | `cloudflare`       |
-| `TENTACLES_SESSION_MODEL`      | the model                                   | `glm-5.2`          |
+| `TENTACLES_SESSION_MODEL`      | the model                                   | `glm-5.3`          |
 | `TENTACLES_SESSION_EFFORT`     | the effort level                            | `max`              |
 | `TENTACLES_WORKSPACE_IMAGE`    | the workspace image                         | `default`          |
-| `TENTACLES_WORKSPACE_SIZE`     | the workspace container's instance type     | `basic`            |
+| `TENTACLES_WORKSPACE_SIZE`     | the workspace container's instance type     | `standard-2`       |
 | `TENTACLES_WORKSPACE_LIFETIME` | the workspace's inactivity time, in minutes | `15`               |
 
 A setting the agent passes to `spawn` wins over its variable.

package/extension/index.js

@@ -15382,7 +15382,13 @@ var SessionStatuses = {
 var SessionStatus = Enum(SessionStatuses);
 var Question = Struct({
 	id: QuestionId,
-	text: String$1
+	text: String$1,
+	repositoryCheck: Union([
+		TaggedStruct("NoRepository", {}),
+		TaggedStruct("Stopped", {}),
+		TaggedStruct("Clean", {}),
+		TaggedStruct("CheckFailed", { output: String$1 })
+	]).pipe(toTaggedUnion("_tag"))
 });
 var SessionDetails = Struct({
 	settings: Settings,
@@ -17105,6 +17111,32 @@ var http = (options) => Object.assign(Object.create(Proto), {
 * @since 4.0.0
 */
 var bearer = /*#__PURE__*/ http({ scheme: "Bearer" });
+// ../../packages/worker-api/src/archive-kinds.ts
+/**
+* The kinds of archive a create request carries. `expandsInto` is where the workspace container
+* expands the kind's archive; a null one is read by the Worker only and never reaches the container.
+*/
+var archiveKinds = {
+	skills: {
+		heading: "Skills",
+		expandsInto: "/skills"
+	},
+	agents: {
+		heading: "Agents",
+		expandsInto: null
+	},
+	context: {
+		heading: "Context",
+		expandsInto: "/context"
+	}
+};
+keys(archiveKinds).flatMap((kind) => {
+	const { expandsInto } = archiveKinds[kind];
+	return expandsInto == null ? [] : [{
+		kind,
+		directory: expandsInto
+	}];
+});
 // ../../packages/worker-api/src/middleware.ts
 /** Every request carries the API key as a bearer token; a provider checks it against its secret. */
 var ApiKey = class extends Service()("tentacles/ApiKey", {
@@ -17121,8 +17153,7 @@ var CreateSession = Struct({
 	parent: Parent,
 	settings: Settings,
 	prompt: String$1,
-	skills: optionalKey(Archive),
-	agents: optionalKey(Archive)
+	...map$5(archiveKinds, () => optionalKey(Archive))
 });
 var Prompt = Struct({
 	text: String$1,
@@ -17209,10 +17240,15 @@ var endpointArguments = (name) => {
 };
 /** What the agent sends to spawn: the glue fills the parent. */
 var SpawnArguments = CreateSession.mapFields((fields) => ({
-	...omit(fields, ["skills", "agents"]),
+	...omit(fields, [
+		"skills",
+		"agents",
+		"context"
+	]),
 	settings: optionalKey(Settings.mapFields(map(optionalKey))),
 	skills: optionalKey(ArraySchema(String$1).annotate({ description: "Paths of skill folders on this machine, each holding a SKILL.md." })),
-	agents: optionalKey(ArraySchema(String$1).annotate({ description: "Paths of agent definition files on this machine." }))
+	agents: optionalKey(ArraySchema(String$1).annotate({ description: "Paths of agent definition files on this machine." })),
+	context: optionalKey(ArraySchema(String$1).annotate({ description: "Paths of files or folders on this machine; the remote agent finds them in /context, each under its own name." }))
 })).mapFields(omit(["parent"]));
 // src/core/tool-table.ts
 var ToolNames = {
@@ -17231,7 +17267,7 @@ var spawnDocument = toJsonSchemaDocument(SpawnArguments);
 var ToolTable = {
 	spawn: ToolEntry.Endpoint({
 		name: ToolNames.spawn,
-		description: "Start a remote agent with a name, a first prompt and optional settings. The settings left out come from the plugin's defaults. Optionally takes the paths of skill folders and agent definition files, which stay fixed for the session. Answers with the new session's id.",
+		description: "Start a remote agent with a name, a first prompt and optional settings. The settings left out come from the plugin's defaults. Optionally takes the paths of skill folders and agent definition files, and the paths of context files or folders the remote agent finds in /context, which stay fixed for the session. Answers with the new session's id.",
 		endpoint: "create",
 		harnesses: bothHarnesses,
 		arguments: {
@@ -17293,7 +17329,13 @@ var entryText = type().pipe(tagsExhaustive({
 	toolResult: (entry) => entry.output,
 	subagentResult: (entry) => entry.text
 }));
-var questionWake = (session, question) => `${agentOf(session)} asks (question ${question.id}):\n${question.text}\n\nAnswer it with the answer tool, passing session ${session.sessionId} and question ${question.id}.`;
+var repositoryCheckText = type().pipe(tagsExhaustive({
+	NoRepository: () => "NoRepository",
+	Stopped: () => "Stopped",
+	Clean: () => "Clean",
+	CheckFailed: ({ output }) => output === "" ? "CheckFailed" : `CheckFailed\n${output}`
+}));
+var questionWake = (session, question) => `${agentOf(session)} asks (question ${question.id}):\n${question.text}\n\nRepository check: ${repositoryCheckText(question.repositoryCheck)}\n\nAnswer it with the answer tool, passing session ${session.sessionId} and question ${question.id}.`;
 var finishWake = (session, lastEntry) => lastEntry == null ? `${agentOf(session)} finished. Read its last message with the messages tool.` : `${agentOf(session)} finished. Its last message:\n${entryText(lastEntry)}`;
 var failureWake = (session, failure) => `${agentOf(session)} failed: ${failure}`;
 // src/core/controller.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asermax/pi-tentacles",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Spawn, steer, question and collect remote coding agents that run in tentacles.",
   "type": "module",
   "license": "MIT",

package/skills/tentacles/SKILL.md

@@ -16,7 +16,7 @@ A remote agent only keeps what it commits and pushes. Its workspace is disposabl
 
 ## Spawn
 
-`spawn` takes a name, the first prompt, the session's settings and, optionally, skills and agent definitions (see Skills and agents). The name shows in your status line, so name it after the agent's task. The settings you leave out come from the plugin's defaults.
+`spawn` takes a name, the first prompt, the session's settings and, optionally, skills, agent definitions and context files (see Skills and agents, and Context files). The name shows in your status line, so name it after the agent's task. The settings you leave out come from the plugin's defaults.
 
 Write the first prompt for someone who has not seen this conversation: the goal, the repository, the branch to push, and what done looks like. Name the repository in the settings when the agent has to work in it, so tentacles clones the repository and, before the agent asks you anything, checks it for work that is not pushed.
 
@@ -30,6 +30,14 @@ Every definition is checked on your machine before anything is sent. When any fa
 
 A remote agent works on its own, so a skill that would stop to ask the person has nobody to ask. Write the handoff so the remote agent decides wherever a skill would stop for the user, ignores any instruction in a skill to ask the user, and lists every such decision in its final report. For a stop point it cannot decide, such as a credential it lacks, say in the handoff what to do, which can be asking you with its question tool.
 
+## Context files
+
+`spawn` takes `context`, the paths of files and folders on your machine that the job needs and the repository does not hold, such as a change's scratch files. Each path lands in the remote agent's `/context` folder under its own name: a file at `/context/<file name>`, a folder at `/context/<folder name>/…`. `/context` is outside the repository, so the files never reach its commits. A folder takes everything under it, a symlink is sent as the file or folder it points to, and every file keeps its permission bits.
+
+The remote agent has a copy that is fixed at spawn. Its edits to the copy are lost when its workspace restarts and never come back to you, so spawn a new remote agent when the job needs different files. The remote agent is told only that you sent files and that they are in `/context`, so say in the handoff what the files are and how to use them.
+
+The paths are checked on your machine before anything is sent. A path that does not exist or cannot be read, two paths with the same name, or files that pack over 5 MB make `spawn` create nothing and return every problem with its path in a Context group, beside the Skills and Agents groups.
+
 ## Being woken
 
 You are woken when a remote agent stops. The wake carries the agent's last message when it finishes, the reason when it fails, and the question when it asks one. You never poll. If you think a wake was missed, run `list`.
@@ -38,6 +46,15 @@ You are woken when a remote agent stops. The wake carries the agent's last messa
 
 A remote agent asks with its question tool and waits for the answer. Answer with `answer`, passing the question's id. Answer it yourself when you can; when the decision is the human's, ask them and answer once they reply. A prompt you send while a question waits does not answer the question. The agent receives the prompt after the question is answered.
 
+Every question comes with a repository check, which tells you whether the remote agent's work is known to be persisted:
+
+- `Clean`: the work is committed and pushed. The question can wait any length of time.
+- `Stopped`: the agent's workspace was not running, so it had nothing pending. The question can wait any length of time.
+- `CheckFailed`: tentacles could not check the workspace, so the agent's work may exist only on the container's disk and is lost when the container stops. The check comes with what the git commands printed, which shows why it failed and is empty when the workspace ran neither command.
+- `NoRepository`: the session's settings name no repository, so tentacles manages none and checked nothing.
+
+A remote agent that has uncommitted changes or unpushed commits cannot ask: its question tool refuses until it commits and pushes.
+
 ## Prompt
 
 `prompt` sends a follow-up or a steer. A follow-up waits for the current run to end; a steer reaches the agent at its next step. Prompting a closed session reopens it.

package/tentacles-helper

@@ -1,7 +1,14 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { readFile, readdir, stat } from "node:fs/promises";
-import { basename, join, relative, resolve, sep } from "node:path";
+import * as fsp from "node:fs/promises";
+import { readFile, realpath, stat } from "node:fs/promises";
+import * as path from "node:path";
+import { basename, join, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import * as fs from "node:fs";
+import { cpus } from "node:os";
+import { Readable } from "node:stream";
 // \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod, mod.exports), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
@@ -26240,7 +26247,13 @@ var SessionStatuses = {
 var SessionStatus = Enum(SessionStatuses);
 var Question = Struct({
 	id: QuestionId,
-	text: String$2
+	text: String$2,
+	repositoryCheck: Union([
+		TaggedStruct("NoRepository", {}),
+		TaggedStruct("Stopped", {}),
+		TaggedStruct("Clean", {}),
+		TaggedStruct("CheckFailed", { output: String$2 })
+	]).pipe(toTaggedUnion("_tag"))
 });
 var SessionDetails = Struct({
 	settings: Settings,
@@ -29256,6 +29269,34 @@ var http = (options) => Object.assign(Object.create(Proto$2), {
 * @since 4.0.0
 */
 var bearer = /*#__PURE__*/ http({ scheme: "Bearer" });
+// ../../packages/worker-api/src/archive-kinds.ts
+/**
+* The kinds of archive a create request carries. `expandsInto` is where the workspace container
+* expands the kind's archive; a null one is read by the Worker only and never reaches the container.
+*/
+var archiveKinds = {
+	skills: {
+		heading: "Skills",
+		expandsInto: "/skills"
+	},
+	agents: {
+		heading: "Agents",
+		expandsInto: null
+	},
+	context: {
+		heading: "Context",
+		expandsInto: "/context"
+	}
+};
+/** The kinds in table order. */
+var archiveKindNames = keys(archiveKinds);
+archiveKindNames.flatMap((kind) => {
+	const { expandsInto } = archiveKinds[kind];
+	return expandsInto == null ? [] : [{
+		kind,
+		directory: expandsInto
+	}];
+});
 // ../../packages/worker-api/src/middleware.ts
 /** Every request carries the API key as a bearer token; a provider checks it against its secret. */
 var ApiKey = class extends Service()("tentacles/ApiKey", {
@@ -29280,8 +29321,7 @@ var CreateSession = Struct({
 	parent: Parent,
 	settings: Settings,
 	prompt: String$2,
-	skills: optionalKey(Archive),
-	agents: optionalKey(Archive)
+	...map$8(archiveKinds, () => optionalKey(Archive))
 });
 var Prompt = Struct({
 	text: String$2,
@@ -30157,10 +30197,10 @@ var ConnectionConfig = all({
 /** The settings a spawn leaves out. */
 var SettingsDefaults = all({
 	provider: String$1("TENTACLES_SESSION_PROVIDER").pipe(withDefault("cloudflare")),
-	model: String$1("TENTACLES_SESSION_MODEL").pipe(withDefault("glm-5.2")),
+	model: String$1("TENTACLES_SESSION_MODEL").pipe(withDefault("glm-5.3")),
 	effort: String$1("TENTACLES_SESSION_EFFORT").pipe(withDefault("max")),
 	image: String$1("TENTACLES_WORKSPACE_IMAGE").pipe(withDefault("default")),
-	size: String$1("TENTACLES_WORKSPACE_SIZE").pipe(withDefault("basic")),
+	size: String$1("TENTACLES_WORKSPACE_SIZE").pipe(withDefault("standard-2")),
 	lifetime: Int("TENTACLES_WORKSPACE_LIFETIME").pipe(withDefault(15))
 });
 // src/helper/client.ts
@@ -30476,16 +30516,25 @@ var exhaustive = exhaustive$1;
 /**
 * What the helper receives for spawn: CreateSession with every setting
 * optional, since the helper fills the rest from its variables, and with the
-* paths of the skills and agents in place of their archives, which the helper packs.
+* paths of the skills, agents and context in place of their archives, which the helper packs.
 */
 var SpawnRequest = CreateSession.mapFields((fields) => ({
-	...omit(fields, ["skills", "agents"]),
+	...omit(fields, [
+		"skills",
+		"agents",
+		"context"
+	]),
 	settings: optionalKey(Settings.mapFields(map$3(optionalKey))),
 	skills: optionalKey(ArraySchema(String$2).annotate({ description: "Paths of skill folders on this machine, each holding a SKILL.md." })),
-	agents: optionalKey(ArraySchema(String$2).annotate({ description: "Paths of agent definition files on this machine." }))
+	agents: optionalKey(ArraySchema(String$2).annotate({ description: "Paths of agent definition files on this machine." })),
+	context: optionalKey(ArraySchema(String$2).annotate({ description: "Paths of files or folders on this machine; the remote agent finds them in /context, each under its own name." }))
 }));
 SpawnRequest.mapFields(omit(["parent"]));
 // ../../node_modules/.pnpm/modern-tar@0.8.6/node_modules/modern-tar/dist/packer-By1HVV7Z.js
+var FILE = "file";
+var LINK = "link";
+var SYMLINK = "symlink";
+var DIRECTORY = "directory";
 var TYPEFLAG = {
 	file: "0",
 	link: "1",
@@ -30645,7 +30694,7 @@ function getHeaderBlocks(header) {
 	];
 }
 var EOF_BUFFER = /* @__PURE__ */ new Uint8Array(1024);
-function createTarPacker$1(onData) {
+function createTarPacker(onData) {
 	let currentHeader = null;
 	let bytesWritten = 0;
 	let finalized = false;
@@ -30694,171 +30743,6 @@ function createTarPacker$1(onData) {
 		}
 	};
 }
-// ../../node_modules/.pnpm/modern-tar@0.8.6/node_modules/modern-tar/dist/web/index.js
-function createTarPacker() {
-	let streamController;
-	let packer;
-	let bodyController = null;
-	let resume = null;
-	let drain = null;
-	let stopped = false;
-	let stopReason;
-	const unblock = () => {
-		resume?.();
-		resume = null;
-		drain = null;
-	};
-	const stop = (reason) => {
-		if (stopped) return;
-		stopped = true;
-		stopReason = reason;
-		bodyController?.error(reason);
-		bodyController = null;
-		streamController.error(reason);
-		unblock();
-	};
-	const abortBody = (reason = AbortSignal.abort().reason) => {
-		bodyController = null;
-		stop(reason);
-	};
-	const checkStopped = () => {
-		if (stopped) throw stopReason;
-	};
-	const emit = (operation) => {
-		checkStopped();
-		try {
-			operation();
-		} catch (error) {
-			stop(error);
-			throw error;
-		}
-		const pending = drain;
-		if (!pending) return;
-		const signal = bodyController?.signal;
-		if (!signal) return;
-		if (signal.aborted) abortBody(signal.reason);
-		else signal.onabort = () => abortBody(signal.reason);
-		return pending.then(checkStopped);
-	};
-	return {
-		readable: new ReadableStream({
-			start(controller) {
-				streamController = controller;
-				packer = createTarPacker$1((chunk) => {
-					const buffer = chunk.buffer;
-					controller.enqueue(buffer instanceof ArrayBuffer && !Reflect.get(buffer, "resizable") ? chunk : new Uint8Array(chunk));
-					if ((controller.desiredSize ?? 1) <= 0) drain ||= new Promise((resolve) => {
-						resume = resolve;
-					});
-				});
-			},
-			pull: unblock,
-			cancel(reason = AbortSignal.abort().reason) {
-				stop(reason);
-			}
-		}, new ByteLengthQueuingStrategy({ highWaterMark: 8388608 })),
-		controller: {
-			add(header) {
-				try {
-					checkStopped();
-					if (bodyController) throw new Error("Previous entry must be completed before adding a new one");
-					packer.add(header);
-				} catch (error) {
-					stop(error);
-					throw error;
-				}
-				return new WritableStream({
-					start(controller) {
-						bodyController = controller;
-					},
-					write(chunk) {
-						return emit(() => {
-							if (!ArrayBuffer.isView(chunk) || chunk[Symbol.toStringTag] !== "Uint8Array") throw new TypeError("Expected a Uint8Array body chunk");
-							packer.write(chunk);
-						});
-					},
-					close() {
-						const result = emit(() => packer.endEntry());
-						if (!result) {
-							bodyController = null;
-							return;
-						}
-						return result.then(() => {
-							bodyController = null;
-						});
-					},
-					abort: abortBody
-				});
-			},
-			finalize() {
-				try {
-					checkStopped();
-					if (bodyController) throw new Error("Cannot finalize while an entry is still active");
-					packer.finalize();
-					streamController.close();
-				} catch (error) {
-					stop(error);
-					throw error;
-				}
-			},
-			error(err) {
-				stop(err);
-			}
-		}
-	};
-}
-async function streamToBuffer(stream) {
-	const chunks = [];
-	const reader = stream.getReader();
-	let totalLength = 0;
-	try {
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			chunks.push(value);
-			totalLength += value.length;
-		}
-		const result = new Uint8Array(totalLength);
-		let offset = 0;
-		for (const chunk of chunks) {
-			result.set(chunk, offset);
-			offset += chunk.length;
-		}
-		return result;
-	} finally {
-		reader.releaseLock();
-	}
-}
-async function packTar(entries) {
-	const { readable, controller } = createTarPacker();
-	const archive = streamToBuffer(readable);
-	try {
-		for (const entry of entries) {
-			const entryStream = controller.add(entry.header);
-			const body = "body" in entry ? entry.body : entry.data;
-			if (!body) {
-				await entryStream.close();
-				continue;
-			}
-			if (body instanceof ReadableStream) await body.pipeTo(entryStream);
-			else if (body instanceof Blob) await body.stream().pipeTo(entryStream);
-			else try {
-				const chunk = await normalizeBody(body);
-				if (chunk.length > 0) {
-					const writer = entryStream.getWriter();
-					await writer.write(chunk);
-					await writer.close();
-				} else await entryStream.close();
-			} catch {
-				throw new TypeError(`Unsupported content type for entry "${entry.header.name}".`);
-			}
-		}
-		controller.finalize();
-	} catch (error) {
-		controller.error(error);
-	}
-	return archive;
-}
 // ../../node_modules/.pnpm/yaml@2.9.1/node_modules/yaml/dist/nodes/identity.js
 var require_identity = /* @__PURE__ */ __commonJSMin(((exports) => {
 	var ALIAS = Symbol.for("yaml.alias");
@@ -37575,34 +37459,410 @@ var checkAgents = (sources) => {
 };
 TaggedError()("ArchiveUnreadable", { message: String$2 });
 var skillFile = "SKILL.md";
-var gzip = async (bytes) => new Uint8Array(await new Response(new Blob([bytes]).stream().pipeThrough(new CompressionStream("gzip"))).arrayBuffer());
-/** Packs entries into a tar.gz, the form `readArchive` reads. */
-var packArchive = (entries) => promise(async () => gzip(await packTar(entries.map((entry) => ({
-	header: {
-		name: entry.path,
-		size: entry.bytes.byteLength,
-		mode: entry.mode
-	},
-	body: entry.bytes
-})))));
 new TextDecoder();
+// ../../node_modules/.pnpm/modern-tar@0.8.6/node_modules/modern-tar/dist/fs/index.js
+var win32Reserved = {
+	":": "",
+	"<": "",
+	">": "",
+	"|": "",
+	"?": "",
+	"*": "",
+	"\"": ""
+};
+function normalizeName(name) {
+	const path = name.replace(/\\/g, "/");
+	if (path.split("/").includes("..") || /^[a-zA-Z]:\.\./.test(path)) throw new Error(`${name} points outside extraction directory`);
+	let relative = path;
+	if (/^[a-zA-Z]:/.test(relative)) relative = relative.replace(/^[a-zA-Z]:[/\\]?/, "");
+	else if (relative.startsWith("/")) relative = relative.replace(/^\/+/, "");
+	if (process.platform === "win32") return relative.replace(/[<>:"|?*]/g, (char) => win32Reserved[char]);
+	return relative;
+}
+var BIGINT_STAT = { bigint: true };
+var WITH_FILE_TYPES = { withFileTypes: true };
+function packTar(sources, options = {}) {
+	const results = /* @__PURE__ */ new Map();
+	const fileHandles = /* @__PURE__ */ new Map();
+	const bodyStreams = /* @__PURE__ */ new Set();
+	let resume = null;
+	let drain = null;
+	let resumeWriter = null;
+	let cancelError;
+	const unblock = () => {
+		const resolve = resume;
+		resume = null;
+		drain = null;
+		resolve?.();
+	};
+	const wakeWriter = () => {
+		resumeWriter?.();
+		resumeWriter = null;
+	};
+	const destroyBody = (body, reason) => {
+		bodyStreams.delete(body);
+		body.destroy(reason);
+	};
+	const closeHandle = (handle) => {
+		const closing = fileHandles.get(handle);
+		if (closing !== null) return closing;
+		const promise = handle.close().finally(() => fileHandles.delete(handle));
+		fileHandles.set(handle, promise);
+		return promise;
+	};
+	const stop = async (reason) => {
+		for (const body of bodyStreams) destroyBody(body, reason);
+		const closing = Promise.allSettled([...fileHandles.keys()].map(closeHandle));
+		results.clear();
+		wakeWriter();
+		for (const result of await closing) if (result.status === "rejected") throw result.reason;
+	};
+	const stream = new Readable({
+		highWaterMark: 8388608,
+		read: unblock,
+		destroy(error, callback) {
+			cancelError = error ?? AbortSignal.abort().reason;
+			unblock();
+			stop(cancelError).then(() => callback(error), (closeError) => callback(error ?? closeError));
+		}
+	});
+	const onError = (error) => stream.destroy(error);
+	const packer = createTarPacker((chunk) => {
+		if (stream.destroyed) throw cancelError;
+		if (!stream.push(Buffer.from(chunk)) && !drain) drain = new Promise((resolve) => {
+			resume = resolve;
+		});
+	});
+	(async () => {
+		const { dereference = false, filter, map, baseDir, concurrency = cpus().length || 8 } = options;
+		let directoryPath;
+		let realBaseDir;
+		let jobs;
+		if (typeof sources === "string") {
+			const source = path.resolve(sources);
+			directoryPath = source;
+			const before = await fsp.stat(source, BIGINT_STAT);
+			if (stream.destroyed) return;
+			const entries = await fsp.readdir(source, WITH_FILE_TYPES);
+			if (stream.destroyed) return;
+			const after = await fsp.stat(source, BIGINT_STAT);
+			if (stream.destroyed) return;
+			jobs = before.dev === after.dev && before.ino === after.ino ? entries.map((entry) => ({
+				type: entry.isDirectory() ? DIRECTORY : FILE,
+				source: path.join(source, entry.name),
+				target: entry.name
+			})) : [];
+		} else jobs = sources.map((source) => ({ ...source }));
+		const seenHardlinks = /* @__PURE__ */ new Map();
+		let jobIndex = 0;
+		let writeIndex = 0;
+		let activeWorkers = 0;
+		let allJobsQueued = false;
+		const writeStreamBody = async (body) => {
+			try {
+				for await (const chunk of body) {
+					if (stream.destroyed) return;
+					packer.write(chunk instanceof Uint8Array ? chunk : Buffer.from(chunk));
+					if (drain) await drain;
+				}
+			} finally {
+				body.off("error", onError);
+				bodyStreams.delete(body);
+			}
+		};
+		const writer = async () => {
+			const readBufferSmall = Buffer.alloc(65536);
+			let readBufferLarge = null;
+			while (true) {
+				if (stream.destroyed) return;
+				if (allJobsQueued && writeIndex >= jobs.length) break;
+				if (!results.has(writeIndex)) {
+					await new Promise((resolve) => {
+						resumeWriter = resolve;
+					});
+					continue;
+				}
+				const result = results.get(writeIndex);
+				results.delete(writeIndex);
+				if (!result) {
+					writeIndex++;
+					controller();
+					continue;
+				}
+				if (result.hardlinkId) {
+					const originalName = result.header.name;
+					const hardlinkTarget = seenHardlinks.get(result.hardlinkId);
+					if (hardlinkTarget) {
+						if (result.body && !(result.body instanceof Uint8Array) && !(result.body instanceof Readable)) await closeHandle(result.body.handle);
+						result.body = void 0;
+						result.header.type = LINK;
+						result.header.linkname = hardlinkTarget.originalName;
+						result.header.size = 0;
+					}
+					if (map) result.header = map(result.header);
+					if (hardlinkTarget) {
+						if (result.header.linkname === hardlinkTarget.originalName) result.header.linkname = hardlinkTarget.mappedName;
+					} else seenHardlinks.set(result.hardlinkId, {
+						originalName,
+						mappedName: result.header.name
+					});
+				}
+				packer.add(result.header);
+				if (drain) await drain;
+				if (stream.destroyed) return;
+				if (result.body) if (result.body instanceof Uint8Array) {
+					if (result.body.length > 0) {
+						packer.write(result.body);
+						if (drain) await drain;
+					}
+				} else if (result.body instanceof Readable) await writeStreamBody(result.body);
+				else {
+					const { handle, size } = result.body;
+					const readBuffer = size > 1048576 ? readBufferLarge ??= Buffer.alloc(1048576) : readBufferSmall;
+					try {
+						let bytesLeft = size;
+						while (bytesLeft > 0 && !stream.destroyed) {
+							const { bytesRead } = await handle.read(readBuffer, 0, Math.min(bytesLeft, readBuffer.length), null);
+							if (bytesRead === 0) break;
+							packer.write(readBuffer.subarray(0, bytesRead));
+							bytesLeft -= bytesRead;
+							if (drain) await drain;
+						}
+					} finally {
+						await closeHandle(handle);
+					}
+				}
+				if (stream.destroyed) return;
+				packer.endEntry();
+				if (drain) await drain;
+				writeIndex++;
+				controller();
+			}
+		};
+		const controller = () => {
+			if (stream.destroyed || allJobsQueued) return;
+			while (activeWorkers < concurrency && jobIndex < jobs.length && jobIndex - writeIndex < concurrency) {
+				activeWorkers++;
+				const currentIndex = jobIndex++;
+				processJob(jobs[currentIndex], currentIndex).catch(onError).finally(() => {
+					activeWorkers--;
+					controller();
+				});
+			}
+			if (activeWorkers === 0 && jobIndex >= jobs.length) {
+				allJobsQueued = true;
+				wakeWriter();
+			}
+		};
+		const processJob = async (job, index) => {
+			let jobResult = null;
+			const target = normalizeName(job.target);
+			try {
+				if (job.type === "content" || job.type === "stream") {
+					let body;
+					let size;
+					const isDir = target.endsWith("/");
+					if (job.type === "stream") {
+						if (!isDir && job.size <= 0 || isDir && job.size !== 0) throw new Error(isDir ? "Streams for directories must have size 0." : "Streams require a positive size.");
+						size = job.size;
+					} else {
+						const content = await normalizeBody(job.content);
+						size = content.length;
+						body = content;
+					}
+					const stat = {
+						size: isDir ? 0 : size,
+						isFile: () => !isDir,
+						isDirectory: () => isDir,
+						isSymbolicLink: () => false,
+						mode: job.mode,
+						mtime: job.mtime ?? /* @__PURE__ */ new Date(),
+						uid: job.uid ?? 0,
+						gid: job.gid ?? 0
+					};
+					if (stream.destroyed) return;
+					if (filter && !filter(target, stat)) return;
+					if (stream.destroyed) return;
+					let header = {
+						name: target,
+						type: isDir ? DIRECTORY : FILE,
+						size: isDir ? 0 : size,
+						mode: stat.mode,
+						mtime: stat.mtime,
+						uid: stat.uid,
+						gid: stat.gid,
+						uname: job.uname,
+						gname: job.gname
+					};
+					if (map) header = map(header);
+					if (stream.destroyed) return;
+					if (!isDir && job.type === "stream") {
+						body = job.content instanceof Readable ? job.content : Readable.fromWeb(job.content);
+						body.once("error", onError);
+						bodyStreams.add(body);
+					}
+					jobResult = {
+						header,
+						body: isDir ? void 0 : body
+					};
+					return;
+				}
+				let source = job.source;
+				let stat = await fsp.lstat(source, BIGINT_STAT);
+				if (stream.destroyed) return;
+				if (dereference && (baseDir !== void 0 || stat.isSymbolicLink())) {
+					const resolvedSource = await fsp.realpath(source);
+					if (stream.destroyed) return;
+					realBaseDir ??= await fsp.realpath(baseDir ?? directoryPath ?? process.cwd());
+					if (stream.destroyed) return;
+					const relativeToBase = path.relative(realBaseDir, resolvedSource);
+					if (relativeToBase === ".." || relativeToBase.startsWith(".." + path.sep) || path.isAbsolute(relativeToBase)) return;
+					if (stat.isSymbolicLink()) {
+						source = resolvedSource;
+						stat = await fsp.lstat(source, BIGINT_STAT);
+						if (stat.isSymbolicLink()) return;
+					}
+				}
+				if (stream.destroyed) return;
+				if (filter && !filter(job.source, stat)) return;
+				if (stream.destroyed) return;
+				let header = {
+					name: target,
+					size: 0,
+					mode: (job.mode ?? Number(stat.mode)) & 4095,
+					mtime: job.mtime === void 0 ? stat.mtime : new Date(job.mtime.getTime()),
+					uid: job.uid ?? Number(stat.uid),
+					gid: job.gid ?? Number(stat.gid),
+					uname: job.uname,
+					gname: job.gname,
+					type: FILE
+				};
+				let body;
+				let hardlinkId;
+				if (stat.isDirectory()) {
+					header.type = DIRECTORY;
+					header.name = target.endsWith("/") ? target : `${target}/`;
+					try {
+						const entries = await fsp.readdir(source, WITH_FILE_TYPES);
+						if (stream.destroyed) return;
+						const after = await fsp.lstat(source, BIGINT_STAT);
+						if (stream.destroyed || !after.isDirectory() || stat.dev !== after.dev || stat.ino !== after.ino) return;
+						for (const d of entries) jobs.push({
+							type: d.isDirectory() ? DIRECTORY : FILE,
+							source: path.join(source, d.name),
+							target: `${header.name}${d.name}`,
+							mtime: job.mtime,
+							uid: job.uid,
+							gid: job.gid,
+							uname: job.uname,
+							gname: job.gname,
+							mode: job.mode
+						});
+					} catch (error) {
+						const code = error.code;
+						if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+					}
+				} else if (stat.isSymbolicLink()) {
+					header.type = SYMLINK;
+					header.linkname = await fsp.readlink(job.source);
+				} else if (stat.isFile()) {
+					header.size = Number(stat.size);
+					let handleToClose;
+					if (stat.nlink > 1n && (process.platform !== "win32" || stat.dev !== 0n && stat.ino !== -1n)) hardlinkId = `${stat.dev}:${stat.ino}`;
+					try {
+						let after;
+						try {
+							if (header.size === 0) after = await fsp.lstat(source, BIGINT_STAT);
+							else {
+								handleToClose = await fsp.open(source, fs.constants.O_NOFOLLOW ?? 0);
+								fileHandles.set(handleToClose, null);
+							}
+						} catch (error) {
+							const code = error.code;
+							if (code === "ELOOP" || code === "ENOENT") return;
+							throw error;
+						}
+						if (stream.destroyed) return;
+						if (after) {
+							if (!after.isFile() || stat.dev !== after.dev || stat.ino !== after.ino) return;
+						} else {
+							const { dev, ino } = await handleToClose.stat(BIGINT_STAT);
+							if (stream.destroyed) return;
+							if (stat.dev !== dev || stat.ino !== ino) return;
+						}
+						if (header.size > 0) {
+							const handle = handleToClose;
+							if (header.size < 32768) {
+								const buffer = Buffer.allocUnsafe(header.size);
+								let offset = 0;
+								while (offset < buffer.length && !stream.destroyed) {
+									const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+									if (bytesRead === 0) break;
+									offset += bytesRead;
+								}
+								body = offset === buffer.length ? buffer : buffer.subarray(0, offset);
+							} else {
+								body = {
+									handle,
+									size: header.size
+								};
+								handleToClose = void 0;
+							}
+						}
+					} finally {
+						if (handleToClose) await closeHandle(handleToClose);
+					}
+				} else return;
+				if (stream.destroyed) return;
+				if (hardlinkId) jobResult = {
+					header,
+					body,
+					hardlinkId
+				};
+				else {
+					if (map) header = map(header);
+					jobResult = {
+						header,
+						body
+					};
+				}
+			} finally {
+				if (stream.destroyed) {
+					if (jobResult?.body instanceof Readable) destroyBody(jobResult.body, cancelError);
+					else if (jobResult?.body && !(jobResult.body instanceof Uint8Array)) await closeHandle(jobResult.body.handle);
+				} else {
+					results.set(index, jobResult);
+					if (index === writeIndex) wakeWriter();
+				}
+			}
+		};
+		controller();
+		await writer();
+		if (!stream.destroyed) {
+			packer.finalize();
+			stream.push(null);
+		}
+	})().catch(onError);
+	return stream;
+}
+fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | (fs.constants.O_NOFOLLOW ?? 0) | fs.constants.O_EXCL;
+Promise.resolve();
+process.platform;
 // src/helper/definitions.ts
-/** Every problem of every path, per group; nothing is sent. */
-var Rejected = TaggedStruct("Rejected", {
-	skills: ArraySchema(Problem),
-	agents: ArraySchema(Problem)
-});
+/** Every problem of every path, per kind; nothing is sent. */
+var Rejected = TaggedStruct("Rejected", { ...map$8(archiveKinds, () => ArraySchema(Problem)) });
 var decoder = new TextDecoder();
 var encoder = new TextEncoder();
-/** A definition file as the helper sends it: its text with the frontmatter repaired when strict YAML rejects it, and the entry carrying that text. */
-var definitionFile = (path, bytes, mode) => {
+/** A definition file as the helper sends it: its text with the frontmatter repaired when strict YAML rejects it, and the package source carrying that text. */
+var definitionFile = (target, bytes, mode) => {
 	const original = decoder.decode(bytes);
 	const text = repairFrontmatter(original);
 	return {
 		text,
-		entry: {
-			path,
-			bytes: text === original ? bytes : encoder.encode(text),
+		source: {
+			type: "content",
+			target,
+			content: text === original ? bytes : encoder.encode(text),
 			mode
 		}
 	};
@@ -37613,87 +37873,136 @@ var problemOf = (path, message) => ({
 	message
 });
 var isNotFound = (cause) => hasProperty(cause, "code") && cause.code === "ENOENT";
-var inspect = (path, kind) => tryPromise({
+var statPath = (path) => tryPromise({
 	try: () => stat(path),
 	catch: (cause) => problemOf(path, isNotFound(cause) ? "does not exist" : `cannot be read: ${String(cause)}`)
-}).pipe(filterOrFail((info) => kind === "folder" ? info.isDirectory() : info.isFile(), () => problemOf(path, `is not a ${kind}`)));
-var readFolder = (path, folder) => tryPromise({
-	try: async () => {
-		const dirents = await readdir(path, {
-			recursive: true,
-			withFileTypes: true
-		});
-		return (await Promise.all(dirents.map(async (dirent) => {
-			const file = join(dirent.parentPath, dirent.name);
-			const info = await stat(file);
-			if (!info.isFile()) return;
-			return {
-				path: `${folder}/${relative(path, file).split(sep).join("/")}`,
-				bytes: await readFile(file),
-				mode: info.mode & 511
-			};
-		}))).filter((entry) => entry != null).toSorted((left, right) => left.path.localeCompare(right.path));
-	},
-	catch: (cause) => problemOf(path, `cannot be read: ${String(cause)}`)
+});
+var inspect = (path, kind) => statPath(path).pipe(filterOrFail((info) => kind === "folder" ? info.isDirectory() : info.isFile(), () => problemOf(path, `is not a ${kind}`)));
+var readText = (path, problemPath) => tryPromise({
+	try: () => readFile(path),
+	catch: (cause) => problemOf(problemPath, `cannot be read: ${String(cause)}`)
 });
 var readSkill = (path) => gen(function* () {
 	yield* inspect(path, "folder");
-	const folder = basename(resolve(path));
-	const entries = yield* readFolder(path, folder);
-	const skill = entries.find((entry) => entry.path === `${folder}/${skillFile}`);
-	if (skill == null) return yield* fail$3(problemOf(path, `has no ${skillFile}`));
-	const { text, entry } = definitionFile(skill.path, skill.bytes, skill.mode);
+	const root = resolve(path);
+	const folder = basename(root);
+	const skillPath = join(root, skillFile);
+	const missing = problemOf(path, `has no ${skillFile}`);
+	const info = yield* tryPromise({
+		try: () => stat(skillPath),
+		catch: (cause) => isNotFound(cause) ? missing : problemOf(path, `cannot be read: ${String(cause)}`)
+	}).pipe(filterOrFail((found) => found.isFile(), () => missing));
+	const { text, source } = definitionFile(`${folder}/${skillFile}`, yield* readText(skillPath, path), info.mode & 511);
+	const realRoot = yield* tryPromise({
+		try: () => realpath(root),
+		catch: (cause) => problemOf(path, `cannot be read: ${String(cause)}`)
+	});
 	return {
-		source: {
+		skill: {
 			folder,
 			path,
 			text
 		},
-		entries: entries.map((existing) => existing === skill ? entry : existing)
+		sources: [{
+			type: "directory",
+			source: realRoot,
+			target: folder
+		}, source],
+		replaced: join(realRoot, skillFile)
 	};
 });
 var readAgent = (path) => gen(function* () {
 	const info = yield* inspect(path, "file");
-	const bytes = yield* tryPromise({
-		try: () => readFile(path),
-		catch: (cause) => problemOf(path, `cannot be read: ${String(cause)}`)
-	});
-	const { text, entry } = definitionFile(basename(path), bytes, info.mode & 511);
+	const { text, source } = definitionFile(basename(path), yield* readText(path, path), info.mode & 511);
 	return {
-		source: {
+		agent: {
 			path,
 			text
 		},
-		entries: [entry]
+		sources: [source]
 	};
 });
-var packGroup = (kind, problems, entries) => gen(function* () {
-	if (problems.length > 0) return yield* fail$3(problems);
-	if (entries.length === 0) return;
-	const archive = yield* packArchive(entries);
-	if (archive.byteLength > 5242880) return yield* fail$3([problemOf(`the ${kind} archive`, `is ${megabytes(archive.byteLength)}, over the ${megabytes(maxArchiveBytes)} limit`)]);
-	return archive;
+/** A context path is checked by its stat alone: nothing in a folder is read here. */
+var readContext = (path) => gen(function* () {
+	const info = yield* statPath(path);
+	if (!info.isDirectory() && !info.isFile()) return yield* fail$3(problemOf(path, "is not a file or a folder"));
+	const source = resolve(path);
+	const target = basename(source);
+	return info.isDirectory() ? {
+		type: "directory",
+		source,
+		target
+	} : {
+		type: "file",
+		source,
+		target
+	};
+});
+/** A problem on every context path whose name an earlier path already has. */
+var duplicateNames = (paths) => {
+	const firstByName = /* @__PURE__ */ new Map();
+	return paths.flatMap((path) => {
+		const name = basename(resolve(path));
+		const first = firstByName.get(name);
+		if (first == null) {
+			firstByName.set(name, path);
+			return [];
+		}
+		return [problemOf(path, `has the same name as ${first}`)];
+	});
+};
+/** Checks every path with the kind's reader (a stat for context paths, a read of the definition file for skills and agents), adds the problems the kind finds across the readable ones, and builds the result only when there is none. */
+var checkPaths = (paths, read, problemsOf, build) => gen(function* () {
+	const [reads, unreadable] = yield* partition(paths, read, { concurrency: "unbounded" });
+	const problems = [...unreadable, ...problemsOf(reads)];
+	return problems.length > 0 ? yield* fail$3(problems) : build(reads);
+});
+var checkSkillPaths = (paths) => checkPaths(paths, readSkill, (reads) => checkSkills(reads.map((read) => read.skill)).problems, (reads) => {
+	const replaced = new Set(reads.map((read) => read.replaced));
+	return {
+		sources: reads.flatMap((read) => read.sources),
+		filter: (path) => !replaced.has(path)
+	};
+});
+var checkAgentPaths = (paths) => checkPaths(paths, readAgent, (reads) => checkAgents(reads.map((read) => read.agent)).problems, (reads) => ({ sources: reads.flatMap((read) => read.sources) }));
+var checkContextPaths = (paths) => checkPaths(paths, readContext, () => duplicateNames(paths), (sources) => ({ sources }));
+var checks = {
+	skills: checkSkillPaths,
+	agents: checkAgentPaths,
+	context: checkContextPaths
+};
+var pack = (kind, { sources, ...options }) => tryPromise({
+	try: async () => {
+		const chunks = [];
+		await pipeline(packTar(sources, {
+			dereference: true,
+			baseDir: "/",
+			...options
+		}), createGzip(), async (packed) => {
+			for await (const chunk of packed) chunks.push(chunk);
+		});
+		return Buffer.concat(chunks);
+	},
+	catch: (cause) => [problemOf(`the ${kind} archive`, `cannot be packed: ${String(cause)}`)]
+}).pipe(filterOrFail((archive) => archive.byteLength <= maxArchiveBytes, (archive) => [problemOf(`the ${kind} archive`, `is ${megabytes(archive.byteLength)}, over the ${megabytes(maxArchiveBytes)} limit`)]));
+var archiveOf = (kind, paths) => gen(function* () {
+	if (paths.length === 0) return;
+	return yield* checks[kind](paths).pipe(flatMap((checked) => pack(kind, checked)));
 }).pipe(result$1);
-/** Reads every path the agent passed, runs worker-api's checks on each group and packs the archives, each present only when its group had paths; fails with every problem of every path, never at the first. */
-var readDefinitions = ({ skills: skillPaths, agents: agentPaths }) => gen(function* () {
-	const [[skillReads, skillUnreadable], [agentReads, agentUnreadable]] = yield* all$1([partition(skillPaths, readSkill, { concurrency: "unbounded" }), partition(agentPaths, readAgent, { concurrency: "unbounded" })], { concurrency: 2 });
-	const [skills, agents] = yield* all$1([packGroup("skills", [...skillUnreadable, ...checkSkills(skillReads.map((read) => read.source)).problems], skillReads.flatMap((read) => read.entries)), packGroup("agents", [...agentUnreadable, ...checkAgents(agentReads.map((read) => read.source)).problems], agentReads.flatMap((read) => read.entries))], { concurrency: 2 });
-	if (isFailure(skills) || isFailure(agents)) return yield* fail$3(Rejected.make({
-		skills: isFailure(skills) ? skills.failure : [],
-		agents: isFailure(agents) ? agents.failure : []
-	}));
+/** Checks every path the agent passed, kind by kind, and packs each kind that had paths into an archive; fails with every problem of every path, never at the first. */
+var packSpawnArchives = (paths) => gen(function* () {
+	const results = yield* all$1(map$8(paths, (kindPaths, kind) => archiveOf(kind, kindPaths)), { concurrency: "unbounded" });
+	if (Object.values(results).some(isFailure)) return yield* fail$3(Rejected.make(map$8(results, (result) => isFailure(result) ? result.failure : [])));
 	const archives = {};
-	if (skills.success != null) archives.skills = skills.success;
-	if (agents.success != null) archives.agents = agents.success;
+	for (const kind of archiveKindNames) {
+		const result = results[kind];
+		if (isSuccess$1(result) && result.success != null) archives[kind] = result.success;
+	}
 	return archives;
 });
 var section = (heading, problems) => `${heading}:\n${problems.map((problem) => `- ${problem.path}: ${problem.message}`).join("\n")}`;
-/** The tool's error text: every problem with its path, the skills' under one heading and the agents' under another. */
-var rejectionText = (rejected) => [
-	"No session was created: some skills or agents have problems.",
-	...rejected.skills.length > 0 ? [section("Skills", rejected.skills)] : [],
-	...rejected.agents.length > 0 ? [section("Agents", rejected.agents)] : []
-].join("\n\n");
+/** The tool's error text: every problem with its path, one section per kind with problems, in the kinds table's order. */
+var rejectionText = (rejected) => ["No session was created: some skills, agents or context have problems.", ...archiveKindNames.flatMap((kind) => rejected[kind].length > 0 ? [section(archiveKinds[kind].heading, rejected[kind])] : [])].join("\n\n");
 // src/helper/command.ts
 var sessionFields = { sessionId: SessionId };
 var PromptRequest = Struct({
@@ -37721,9 +38030,10 @@ var commands = {
 		const request = yield* decodeArguments(SpawnRequest, json);
 		const defaults = yield* SettingsDefaults;
 		const client = yield* TentaclesClient;
-		const archives = yield* readDefinitions({
+		const archives = yield* packSpawnArchives({
 			skills: request.skills ?? [],
-			agents: request.agents ?? []
+			agents: request.agents ?? [],
+			context: request.context ?? []
 		});
 		return yield* client.sessions.create({ payload: {
 			name: request.name,