Multiplayer agent harness for work.
Read published skill sources without starting sandboxes (#1280)
Regan Belldfdde0bc89e3
diff --git a/docs/skill-registry.md b/docs/skill-registry.mdindex 2c164b0ec..17e5c7149 100644--- a/docs/skill-registry.md+++ b/docs/skill-registry.md@@ -70,3 +70,20 @@ commit.The skills are governed store records, visible and auditable on the admin Skills page, rather thanungoverned files on each box.++## Reading published skills++The skill index advertises `skill://<name>/SKILL.md` for the agent's `read` tool.+These read-only references resolve the currently visible, screened published skill+without creating or waking a sandbox. Relative manifest files can be read at+`skill://<name>/<relative-path>`. Unavailable skills and invalid paths return no file.++Shell commands still use `skills/<name>/...`. Filesystem reads and commands referencing a+skill materialize its assets when needed, including pack files under the path named+in the skill body. Ordinary filesystem reads and writes+retain their existing behavior, including local edits; they are distinct from the+published source. Publish changes through the skill API to update that source.++Command detection uses literal skill paths. Before executing a command that constructs+its asset paths dynamically, read the needed file at its `skills/...` filesystem path+to materialize it.diff --git a/plugins/onboarding/skills/onboarding/SKILL.md b/plugins/onboarding/skills/onboarding/SKILL.mdindex 65745201a..6368a20b3 100644--- a/plugins/onboarding/skills/onboarding/SKILL.md+++ b/plugins/onboarding/skills/onboarding/SKILL.md@@ -75,7 +75,7 @@ form, never into chat.### Personal connectionsCheck the live credential inventory first. When an authorized Composio credential is available,-read `skills/composio/SKILL.md`, discover available apps, and use its consent flow for the+read `skill://composio/SKILL.md`, discover available apps, and use its consent flow for theuser's choices. Reuse their connected accounts after checking identity and permissions;a project key is not proof that a personal account is connected. Do not ask them tocreate OAuth apps for connections this source already provides. Do not infer that Composio is unavailable from an empty direct OAuth listdiff --git a/skills-seed/cloud-cli/SKILL.md b/skills-seed/cloud-cli/SKILL.mdindex 7d00c2920..0d507f3c3 100644--- a/skills-seed/cloud-cli/SKILL.md+++ b/skills-seed/cloud-cli/SKILL.md@@ -26,7 +26,7 @@ If it is missing, say so and pick a path rather than failing halfway:provider's own installer, into the workspace or `$HOME`, not a system path. Say that youinstalled it; it lasts as long as the machine's disk.- **Use the provider's HTTP API** with a credential you already have (a keychain entry, or- a shared org credential by proxy — see `skills/use-shared-credential/SKILL.md`).+ a shared org credential by proxy — see `skill://use-shared-credential/SKILL.md`).- **Ask the operator** to add the CLI to the sandbox image if this will recur. That is thedurable fix; a per-turn install is not.@@ -61,7 +61,7 @@ The platform recognizes these as device-flow logins and runs them as **durable psessions**: the command prints the verification URL and one-time code immediately and keepspolling across turns — it does not block your turn or die at teardown. Give the user the URLand the code, tell them to approve and then say "done". See-`skills/interactive-login/SKILL.md` for how to drive that from the background tool.+`skill://interactive-login/SKILL.md` for how to drive that from the background tool.On the next turn, run the same login command again (or any provider command): if approvallanded, the platform reports you are already authenticated and the token is cached; if it isdiff --git a/skills-seed/connect-apps/SKILL.md b/skills-seed/connect-apps/SKILL.mdindex c92665d16..6b89345be 100644--- a/skills-seed/connect-apps/SKILL.md+++ b/skills-seed/connect-apps/SKILL.md@@ -6,7 +6,7 @@ description: Connect an administrator-enabled SaaS app for a user with a one-tim## Connecting SaaS appsCheck the live credential inventory first. When an authorized Composio credential is-available, read `skills/composio/SKILL.md` and use its discovery and consent flow instead+available, read `skill://composio/SKILL.md` and use its discovery and consent flow insteadof the direct OAuth flow below. An empty direct OAuth list or a native`oauth_not_configured` error does not describe Composio availability. Preserve explicitapp restrictions and account permissions; never switch credentials to evade a denial.diff --git a/skills-seed/github-gitlab/SKILL.md b/skills-seed/github-gitlab/SKILL.mdindex 2a54dbffa..260c9ea8c 100644--- a/skills-seed/github-gitlab/SKILL.md+++ b/skills-seed/github-gitlab/SKILL.md@@ -23,7 +23,7 @@ a write, ask. Do not infer permission from a login merely being present on the cprovider account (for example, `gh api user --jq .login`) and the Git transport's authconfiguration; a CLI API identity alone does not prove which account Git will use.- **Shared org credential:** if listed in the prompt, select its slug and use the- core-hosted smart HTTP remote in `skills/use-shared-credential/SKILL.md`. This uses+ core-hosted smart HTTP remote in `skill://use-shared-credential/SKILL.md`. This usesthe configured shared account, even when a personal OAuth connector is live.Its name is an admin label, not a verified upstream username.- **Connected app:** use only advertised capabilities. API access does not by itselfdiff --git a/skills-seed/popular-web-designs/SKILL.md b/skills-seed/popular-web-designs/SKILL.mdindex d6e7b3e3a..4bd99c497 100644--- a/skills-seed/popular-web-designs/SKILL.md+++ b/skills-seed/popular-web-designs/SKILL.md@@ -30,7 +30,7 @@ have not named one, use your deployment's house-style skill (a `*-design` skill1. Pick a design from the catalog below2. Read it: `read skills/popular-web-designs/templates/<site>.md`3. Use the design tokens and component specs when generating HTML-4. Build with `write`, then serve the result with the `publish` skill (`skills/publish/SKILL.md`)+4. Build with `write`, then serve the result with the `publish` skill (`skill://publish/SKILL.md`)Each template includes an **Implementation Notes** block at the top with:diff --git a/skills-seed/publish/SKILL.md b/skills-seed/publish/SKILL.mdindex 378b55c04..ace556be3 100644--- a/skills-seed/publish/SKILL.md+++ b/skills-seed/publish/SKILL.md@@ -25,9 +25,9 @@ asked for a different look:- **The deployment's house-style skill** — if a `*-design` skill is installed (list`skills/`), it carries the org's look as ready-to-paste CSS and design tokens. Startthere for the look.-- **`skills/taste-skill/SKILL.md`** — the design _process_: reading the brief, layout,+- **`skill://taste-skill/SKILL.md`** — the design _process_: reading the brief, layout,hierarchy, verifying the result, avoiding generic AI-design slop.-- **`skills/popular-web-designs/SKILL.md`** — when the user wants a specific visual+- **`skill://popular-web-designs/SKILL.md`** — when the user wants a specific visualreference (Stripe, Linear, Vercel…).This is about the page a person sees — skip it for an internal-only API or a script withdiff --git a/skills-seed/taste-skill/SKILL.md b/skills-seed/taste-skill/SKILL.mdindex 4c70aff2c..594d35f4d 100644--- a/skills-seed/taste-skill/SKILL.md+++ b/skills-seed/taste-skill/SKILL.md@@ -17,7 +17,7 @@ organization's **house style**: if the deployment installs a `*-design` skill (lit only when the user names a different brand or asks for a one-off exploration.If the user wants a _known brand's_ look (Stripe, Linear, Vercel, Notion…), read-`skills/popular-web-designs/SKILL.md` for the visual vocabulary and let this skill drive+`skill://popular-web-designs/SKILL.md` for the visual vocabulary and let this skill drivethe process.## The playbook@@ -36,7 +36,7 @@ anything externally facing or high-fidelity. Two adjustments for this runtime:You have a real computer, not a hosted design canvas. Build the artifact as files in yourworkspace, verify it locally, and when it should outlive the turn ship it with the-`publish` skill (`skills/publish/SKILL.md`).+`publish` skill (`skill://publish/SKILL.md`).- **`write` / `read` / `execute`** — author files, install deps, run build steps.- **`background`** — run a dev server (`PORT=8080 node server.js`) so you can look at it.diff --git a/src/api/agent-api-catalog.ts b/src/api/agent-api-catalog.tsindex fbe985748..5816a38de 100644--- a/src/api/agent-api-catalog.ts+++ b/src/api/agent-api-catalog.ts@@ -675,7 +675,7 @@ const FAMILIES: AgentApiFamily[] = [((m === "PUT" || m === "DELETE") && p.startsWith("/v1/skills/")) ||(m === "POST" && /^\/v1\/skills\/[^/]+\/restore$/.test(p)),guidance:- "Save a skill when you've worked out a repeatable procedure worth keeping (a checklist, a multi-step flow, a house style) — it auto-loads (skills/<name>/SKILL.md) on every future turn. The skill homes in THIS conversation's scope: in a 1:1 DM it's yours alone; in a private channel or group DM it's owned by that room and every member can edit or delete it (the audit trail records who changed what); a public channel stays owner-only. Write the `body` as a plain-step recipe addressed to your future self; edit or delete it as it goes stale.",+ "Save a skill when you've worked out a repeatable procedure worth keeping (a checklist, a multi-step flow, a house style) — it is advertised for reading at skill://<name>/SKILL.md on future turns. The skill homes in THIS conversation's scope: in a 1:1 DM it's yours alone; in a private channel or group DM it's owned by that room and every member can edit or delete it (the audit trail records who changed what); a public channel stays owner-only. Write the `body` as a plain-step recipe addressed to your future self; edit or delete it as it goes stale.",routes: [{method: "POST",diff --git a/src/core/orchestrator.ts b/src/core/orchestrator.tsindex 395125af5..ec240cc0b 100644--- a/src/core/orchestrator.ts+++ b/src/core/orchestrator.ts@@ -1604,6 +1604,7 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {provisionResource,provisionOwnerAuth,ensureSkillTree,+ readSkill,provisionForReach,reclaimBox,provisionPending,@@ -2160,6 +2161,7 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {...(ownerAuthCommand ? { ownerAuthCommand } : {}),...(scopedCommand ? { scopedCommand } : {}),ensureSkillTree,+ readSkill,...(reachAvailable? {reach: {@@ -2624,7 +2626,19 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {? resumeNote({ backgroundJobs: !!backgroundBroker, workRecorded: !!resume }): baseText;const isPollFire = automatedTurn && !!input.surface && isPollSurface(input.surface);- const sessionUsedTools = visibleHistory.some((e) => e.type === "tool_call");+ const sessionUsedTools = visibleHistory.some(+ (e) =>+ e.type === "tool_call" &&+ !(+ e.payload !== null &&+ typeof e.payload === "object" &&+ "tool" in e.payload &&+ e.payload.tool === "read" &&+ "path" in e.payload &&+ typeof e.payload.path === "string" &&+ e.payload.path.startsWith("skill://")+ ),+ );if (!strictReadOnly &&deps.eagerProvision &&diff --git a/src/core/orchestrator/sandboxes.ts b/src/core/orchestrator/sandboxes.tsindex 6266122eb..56a5383ab 100644--- a/src/core/orchestrator/sandboxes.ts+++ b/src/core/orchestrator/sandboxes.ts@@ -10,8 +10,11 @@ import {import type { DeviceFlowCutoverMode } from "../../credentials/device-flow-cutover.ts";import { expandServiceAliases } from "../../credentials/resident-paths.ts";import { shq } from "../../util/shell.ts";-import { createSkillMaterializer, safeSkillDirName } from "../../skills/materialize.ts";-import type { SkillResolution } from "../../skills/skill-store.ts";+import { createSkillMaterializer, renderSkillBody, safeSkillDirName } from "../../skills/materialize.ts";+import { safeSkillFilePath, type SkillResolution } from "../../skills/skill-store.ts";+import { isSafeSkillName } from "../../skills/skill-name.ts";+import { isSkillMaterializationControlPath } from "../../skills/materialization-paths.ts";+import type { ReadResult } from "../../tools/primitives.ts";import { TURN_FILES_DIR } from "../attachments.ts";import { errMessage, swallow, swallowAs } from "../../util/errors.ts";import { sleep } from "../../util/async.ts";@@ -300,19 +303,35 @@ export function createTurnSandboxes(ctx: TurnSandboxContext) {box.handle = handle;return handle;};+ const readSkill = async (path: string): Promise<ReadResult> => {+ const missing = { content: null, sourceScopeId: null };+ const match = /^skill:\/\/([^/]+)\/(.+)$/.exec(path);+ if (!match || !isSafeSkillName(match[1]!)) return missing;+ const [, name, file] = match;+ try {+ if (safeSkillFilePath(file!) !== file || isSkillMaterializationControlPath(`skills/${name}/${file}`))+ return missing;+ } catch {+ return missing;+ }+ const resolution = (await visibleSkillsForTurn()).find((r) => r.skill?.manifest.name === name);+ if (!resolution?.skill) return missing;+ const content =+ file === "SKILL.md"+ ? renderSkillBody(resolution)+ : resolution.skill.manifest.files?.find((f) => f.path === file)?.content;+ if (content === undefined) return missing;+ if (deps.skills)+ void deps.skills.recordUse(resolution.skill.id).catch((e) => swallow("orchestrator: skill recordUse", e));+ return { content, sourceScopeId: resolution.skill.scopeId };+ };const laidTrees = new Set<string>();- const visibleSkillByDir = new Map<string, SkillResolution>();- for (const r of visibleSkills) {- if (r.skill) visibleSkillByDir.set(safeSkillDirName(r.skill.manifest.name), r);- }- const ensureSkillTree = async (skillDir: string, sandboxId?: string): Promise<void> => {+ const materializeSkillTree = async (handle: SandboxHandle, r: SkillResolution, sandboxId?: string): Promise<void> => {+ const skillDir = safeSkillDirName(r.skill!.manifest.name);const treeKey = `${sandboxId ?? "default"}:${skillDir}`;if (laidTrees.has(treeKey)) return;- const r = visibleSkillByDir.get(skillDir);- if (!r) return;const start = Date.now();try {- const handle = sandboxId ? await provisionResource(sandboxId) : await provision();await skillMaterializer.materializeTree(deps.sandbox, handle, r, [], async () => {const latest = (await visibleSkillsForTurn()).find((candidate) => candidate.skill && safeSkillDirName(candidate.skill.manifest.name) === skillDir,@@ -337,6 +356,17 @@ export function createTurnSandboxes(ctx: TurnSandboxContext) {emitGapWork("skills_materialize", start, Date.now());}};+ const ensureSkillTree = async (skillDir: string, sandboxId?: string): Promise<void> => {+ const current = await visibleSkillsForTurn();+ const requested = current.filter(+ (r) => r.skill && (skillDir === ".packs" ? r.skill.pack : r.skill.manifest.name === skillDir),+ );+ if (!requested.length) return;+ const handle = sandboxId ? await provisionResource(sandboxId) : await provision();+ for (const r of requested) {+ await materializeSkillTree(handle, r, sandboxId);+ }+ };const provisionResource = (id: string): Promise<SandboxHandle> => {const existing = resourceHandles.get(id);if (existing) return Promise.resolve(existing);@@ -634,6 +664,7 @@ export function createTurnSandboxes(ctx: TurnSandboxContext) {provisionResource,provisionOwnerAuth,ensureSkillTree,+ readSkill,provisionForReach,reclaimBox,provisionPending: () => provisionInFlight !== null,diff --git a/src/harness/agent-tools.ts b/src/harness/agent-tools.tsindex f728ca7f6..1a73767aa 100644--- a/src/harness/agent-tools.ts+++ b/src/harness/agent-tools.ts@@ -940,9 +940,10 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):const read = defineTool({name: "read",label: "read",- description: "Read a file from the workspace (scope, then global). Returns its contents.",+ description:+ "Read published skill sources at skill://<name>/<path> without a sandbox, or workspace files (scope, then global). Returns contents.",parameters: Type.Object({- path: Type.String({ description: "Relative path within the workspace." }),+ path: Type.String({ description: "Published skill URI or relative path within the workspace." }),}),async execute(callId, params) {const tc = ref.current;diff --git a/src/onboarding/onboarding.ts b/src/onboarding/onboarding.tsindex bae883c97..000419ce6 100644--- a/src/onboarding/onboarding.ts+++ b/src/onboarding/onboarding.ts@@ -68,7 +68,7 @@ export function renderPendingOnboardingPrompt(status: OnboardingStatus, version"","Onboarding is a high-priority setup task; already knowing who they are is no reason to skip it.","",- "Before ordinary work in this personal DM, read `skills/onboarding/SKILL.md` and follow its complete ordered flow. Keep each turn light, but do not confuse a greeting or existing profile data with completion.",+ "Before ordinary work in this personal DM, read `skill://onboarding/SKILL.md` and follow its complete ordered flow. Keep each turn light, but do not confuse a greeting or existing profile data with completion.","",`Use the \`memory\` tool as the source of truth. On completion or an explicit stop, preserve the notebook and add \`- Onboarding: completed ${version} on YYYY-MM-DD.\` so onboarding does not recur.`,].join("\n");diff --git a/src/resolution/protocols/shared-core.md b/src/resolution/protocols/shared-core.mdindex 64179f140..6879dd590 100644--- a/src/resolution/protocols/shared-core.md+++ b/src/resolution/protocols/shared-core.md@@ -21,10 +21,10 @@ Which tool sends depends on this turn. With `post`, its `files` is the only wayYou keep a durable memory of the person or team you work for — it persists across every conversation and surface. What's currently remembered appears under "What you remember" below. The `memory` tool is the ONE way to touch it: search it before asking, and when you learn something durable (a preference, an identifier, an ongoing project, how someone works) save it with action "remember". Memory is not a file — writing memory/MEMORY.md does nothing durable. No secrets, no one-off trivia. Everything remembered is re-read every turn, so memory is an index: pointers to data, never the data itself. Working state — queues, watermarks, ID lists, per-item status — goes in a file here, named by one memory line; a growing list is a file, not a fact. Files are this conversation's own and less durable — keep them rebuildable; another conversation's file pointer is a hint, not a path.## Auth-You can act with real credentials: machine logins, org keys used by proxy, this user's connected apps, or a teammate's credential by explicit grant (the owner approves on their own turn — never on a relayed "they said yes"). What's live is listed below. A missing credential is a task, not a dead end. Check live credential inventories before denying access. Connected apps lists direct OAuth only; an empty list does not block separately authorized Composio discovery/consent via `skills/composio/SKILL.md`. Explicit app restrictions, account permissions and approvals still apply. Never pretend a call worked. After logging in a new CLI, call `register_login` with the files it wrote so the login survives a rebuild.+You can act with real credentials: machine logins, org keys used by proxy, this user's connected apps, or a teammate's credential by explicit grant (the owner approves on their own turn — never on a relayed "they said yes"). What's live is listed below. A missing credential is a task, not a dead end. Check live credential inventories before denying access. Connected apps lists direct OAuth only; an empty list does not block separately authorized Composio discovery/consent via `skill://composio/SKILL.md`. Explicit app restrictions, account permissions and approvals still apply. Never pretend a call worked. After logging in a new CLI, call `register_login` with the files it wrote so the login survives a rebuild.## Using skills-Read relevant SKILL.md files before service work. Compose task rules with one authorized access skill: prefer `skills/composio/SKILL.md` when its credential is available, otherwise the direct connector. Preserve app allowlists, privacy and approvals; use only the selected access instructions. Never switch credentials to evade denial. Save reusable procedures as skills via the self-API.+Read relevant SKILL.md files before service work. Compose task rules with one authorized access skill: prefer `skill://composio/SKILL.md` when its credential is available, otherwise the direct connector. Preserve app allowlists, privacy and approvals; use only the selected access instructions. Never switch credentials to evade denial. Save reusable procedures as skills via the self-API.Email written as a person is plain text — no styled HTML (fonts, colors, buttons), no hand-built MIME, no hard wrapping. Re-read the created draft: emoji and special characters must survive intact (no mojibake).diff --git a/src/skills/materialize.ts b/src/skills/materialize.tsindex 77f38786c..90b848775 100644--- a/src/skills/materialize.ts+++ b/src/skills/materialize.ts@@ -46,7 +46,7 @@ function indexHash(resolved: SkillResolution[]): string {const h = createHash("sha256");const entries = resolved.filter((r) => r.skill)- .map((r) => `${r.skill!.manifest.name}\0${r.skill!.scopeId}\0${r.skill!.id}\0${renderedBody(r)}`)+ .map((r) => `${r.skill!.manifest.name}\0${r.skill!.scopeId}\0${r.skill!.id}\0${renderSkillBody(r)}`).sort();for (const e of entries) {h.update(e);@@ -66,7 +66,7 @@ function treeHash(resolution: SkillResolution, bundles: SkillBundle[]): string {.sort().join("\0");return createHash("sha256")- .update(renderedBody(resolution))+ .update(renderSkillBody(resolution)).update("\0").update(files).update("\0")@@ -78,7 +78,7 @@ function packRoot(resolution: SkillResolution): string | null {return resolution.skill?.pack ? `${SKILL_PACKS_DIR}/${safeSkillDirName(resolution.skill.pack.packId)}` : null;}-function renderedBody(resolution: SkillResolution): string {+export function renderSkillBody(resolution: SkillResolution): string {const body = resolution.skill!.manifest.body;const root = packRoot(resolution);return root@@ -265,7 +265,7 @@ async function materializeSkillIndexUnlocked(if (!r.skill) continue;entries.push({path: `${SKILLS_DIR}/${safeSkillDirName(r.skill.manifest.name)}/SKILL.md`,- content: renderedBody(r),+ content: renderSkillBody(r),});}entries.push({@@ -337,7 +337,7 @@ async function materializeSkillTreeUnlocked(await sandbox.removeDir(handle, dir);}- const entries: LayEntry[] = [{ path: `${dir}/SKILL.md`, content: renderedBody(resolution) }];+ const entries: LayEntry[] = [{ path: `${dir}/SKILL.md`, content: renderSkillBody(resolution) }];for (const f of files) {let rel: string;try {@@ -426,11 +426,11 @@ export function skillsIndex(resolved: SkillResolution[], provenanceScopes: readoconst m = r.skill!.manifest;const shadow = r.shadowed.length ? " (shadows a broader-scope skill of the same name)" : "";const source = provenance.has(r.skill!.scopeId) ? ` [from ${r.skill!.scopeId}]` : "";- return `- **${m.name}**${source} — ${m.description}${shadow} → read \`${SKILLS_DIR}/${safeSkillDirName(m.name)}/SKILL.md\``;+ return `- **${m.name}**${source} — ${m.description}${shadow} → read \`skill://${safeSkillDirName(m.name)}/SKILL.md\``;});return ["## Skills",- "You have these skills available. To use one, read its SKILL.md and follow it (run its steps with your tools):",+ "Read published skills with the read tool at skill://<name>/SKILL.md; this does not start a sandbox. Read relative skill files at skill://<name>/<path>. These are read-only published sources, not filesystem paths. Execute scripts and access working copies under skills/<name>/ in the sandbox; ordinary filesystem reads preserve local edits.",...lines,].join("\n");}diff --git a/src/tools/primitives.ts b/src/tools/primitives.tsindex 3206e0f55..f5c265c22 100644--- a/src/tools/primitives.ts+++ b/src/tools/primitives.ts@@ -71,9 +71,9 @@ import type { CapabilityClaims } from "../auth/capability-token.ts";import type { VisibleCron } from "../api/app.ts";import { createPlaygroundArtifact, type PlaygroundArtifact } from "../playgrounds/playground.ts";-const SKILL_SKILLMD_RE = /^(?:\.\/)?skills\/([^/]+)\/SKILL\.md$/;+const SKILL_FILE_RE = /^(?:\.\/)?skills\/([^/]+)\/.+$/;function skillTreeDirFor(path: string): string | null {- const m = SKILL_SKILLMD_RE.exec(path);+ const m = SKILL_FILE_RE.exec(path);return m ? m[1]! : null;}@@ -143,7 +143,7 @@ export class CommandDenied extends Error {}}-interface ReadResult {+export interface ReadResult {content: string | null;sourceScopeId: ScopeId | null;shared?: true;@@ -432,6 +432,7 @@ export interface ToolContextDeps {provisionOwnerAuth?: () => Promise<SandboxHandle>;ownerAuthCommand?: (command: string) => string;scopedCommand?: (command: string) => string;+ readSkill?: (path: string) => Promise<ReadResult>;ensureSkillTree?: (skillDir: string, sandboxId?: string) => Promise<void>;reach?: {resolveChannel(query: string): Promise<ReachResolution>;@@ -811,6 +812,8 @@ export function createToolContext(deps: ToolContextDeps): ToolContext {async read(path: string, signal?: AbortSignal): Promise<ReadResult> {signal?.throwIfAborted();+ if (path.startsWith("skill://"))+ return deps.readSkill ? withAbort(() => deps.readSkill!(path), signal) : { content: null, sourceScopeId: null };if (path === MEMORY_FILE && deps.memory && deps.memoryScopeId) {if (!deps.memoryAccess?.read.includes(deps.memoryScopeId)) {throw new Error("memory recall is not enabled for this conversation; use the `memory` tool when enabled");@@ -878,6 +881,8 @@ export function createToolContext(deps: ToolContextDeps): ToolContext {},async write(path: string, data?: string, share?: ShareDirective[]): Promise<WriteResult> {+ if (path.startsWith("skill://"))+ throw new Error("Published skill sources are read-only; edit skills through the skill API.");const wantShare = share !== undefined && share.length > 0;if (data === undefined && !wantShare) {throw new Error("write needs `data` to save content, `share` to grant access, or both");diff --git a/test/deployment-skill.test.ts b/test/deployment-skill.test.tsindex c43aeeacf..8c1bc56cf 100644--- a/test/deployment-skill.test.ts+++ b/test/deployment-skill.test.ts@@ -108,7 +108,7 @@ test("connector onboarding is governed by the live admin-configured list", () =>assert.doesNotMatch(skill, /Slack and Google first|Slack, Google, Notion, Linear, and GitHub/);}for (const skill of [onboarding, connectApps]) {- assert.match(skill, /skills\/composio\/SKILL\.md/);+ assert.match(skill, /skill:\/\/composio\/SKILL\.md/);assert.match(skill, /never switch credentials to evade a denial/i);assert.doesNotMatch(skill, /If it says none are enabled, skip|offer none when that list is/);}diff --git a/test/onboarding.test.ts b/test/onboarding.test.tsindex 573fcfc96..62575821b 100644--- a/test/onboarding.test.ts+++ b/test/onboarding.test.ts@@ -74,7 +74,7 @@ test("a new personal DM gets the high-priority pending onboarding prompt", asyncassert.match(sys.reply ?? "", /## Pending Onboarding/);assert.match(sys.reply ?? "", /high-priority setup task/);assert.match(sys.reply ?? "", /no reason to skip it/);- assert.match(sys.reply ?? "", /skills\/onboarding\/SKILL\.md/);+ assert.match(sys.reply ?? "", /skill:\/\/onboarding\/SKILL\.md/);});test("completed or dismissed onboarding markers suppress the pending prompt", async () => {diff --git a/test/prompt-modes.test.ts b/test/prompt-modes.test.tsindex 3448bd43d..3637f6059 100644--- a/test/prompt-modes.test.ts+++ b/test/prompt-modes.test.ts@@ -288,7 +288,7 @@ test("shared-core platform guidance reaches both the DM and the spine prompt", aassert.match(prompt, /## Auth/);assert.match(prompt, /## Using skills/);assert.match(prompt, /Compose task rules with one authorized access skill/);- assert.match(prompt, /prefer `skills\/composio\/SKILL.md`/);+ assert.match(prompt, /prefer `skill:\/\/composio\/SKILL.md`/);assert.match(prompt, /Never switch credentials to evade denial/);assert.doesNotMatch(prompt, /## Scheduling & self-configuration/);}diff --git a/test/skills-lazy-read-seam.test.ts b/test/skills-lazy-read-seam.test.tsindex 27126e5f6..db3a97279 100644--- a/test/skills-lazy-read-seam.test.ts+++ b/test/skills-lazy-read-seam.test.ts@@ -62,13 +62,13 @@ test("a leading ./ on the SKILL.md path still triggers materialization", async (assert.deepEqual(seen, ["taste-skill"]);});-test("reading an asset inside a skill dir does NOT trigger materialization (only SKILL.md does)", async () => {+test("reading assets inside skill directories materializes their trees", async () => {const seen: string[] = [];const tc = ctx((d) => seen.push(d));await tc.read("skills/popular-web-designs/scripts/render.py");await tc.read("skills/foo/references/notes.md");await tc.read("reports/report.md");- assert.deepEqual(seen, [], "no lazy trigger for non-SKILL.md reads");+ assert.deepEqual(seen, ["popular-web-designs", "foo"]);});test("executing a skill's script on a cold box (no prior SKILL.md read) materializes its tree first", async () => {diff --git a/test/skills-source-read.test.ts b/test/skills-source-read.test.tsnew file mode 100644index 000000000..7f38cca18--- /dev/null+++ b/test/skills-source-read.test.ts@@ -0,0 +1,184 @@+import "./support/auto-fake-sprites.ts";+import { test, type TestContext } from "node:test";+import assert from "node:assert/strict";+import { buildApp } from "../src/wiring.ts";+import { testConfig } from "./support/test-config.ts";+import type { TurnRequest } from "../src/types.ts";++async function fixture(t: TestContext) {+ const built = buildApp(testConfig());+ await built.deploymentLayerReady;+ t.after(async () => {+ built.scheduler.stop();+ built.deploymentLayerRefresh.stop();+ await built.runtime.stop();+ });+ let provisions = 0;+ const provision = built.sandbox.provision.bind(built.sandbox);+ built.sandbox.provision = async (...args) => {+ provisions++;+ return provision(...args);+ };+ const turn = async (text: string, actor = "U1") => {+ const result = await built.app.turn({+ surface: "test",+ actor: { externalId: actor },+ conversation: { kind: "dm", threadRef: `dm:${actor}:skill-source` },+ text,+ } as TurnRequest);+ assert.equal(result.status, "ok", JSON.stringify(result));+ return result.reply ?? "";+ };+ const publish = async (scopeId: string, body: string, packId?: string) => {+ const skill = await built.skills.create({+ scopeId,+ createdBy: "U1",+ ...(packId ? { pack: { packId, commit: "c", upstreamName: "source-helper" } } : {}),+ manifest: {+ name: "source-helper",+ description: "source test",+ body,+ requiredCapabilities: [],+ files: [{ path: "references/example.txt", content: "PUBLISHED_ASSET" }],+ },+ });+ await built.skills.review(skill.id, "reviewer", []);+ await built.skills.publish(skill.id);+ return skill;+ };+ return { ...built, turn, publish, provisions: () => provisions };+}++test("published skill sources and assets read without a sandbox, respecting scope and archive", async (t) => {+ const b = await fixture(t);+ const skill = await b.publish("personal:U1", "PUBLISHED_BODY");+ assert.match(await b.turn("!sysprompt"), /skill:\/\/source-helper\/SKILL.md/);+ assert.equal(await b.turn("!read skill://source-helper/SKILL.md"), "PUBLISHED_BODY");+ assert.equal(await b.turn("!read skill://source-helper/references/example.txt"), "PUBLISHED_ASSET");+ assert.match(await b.turn("!read skill://source-helper/SKILL.md", "U2"), /no file/);+ await b.skills.archive(skill.id);+ assert.match(await b.turn("!read skill://source-helper/SKILL.md"), /no file/);+ assert.equal(b.provisions(), 0);+});++test("published skill reads reject invalid and control paths without provisioning", async (t) => {+ const b = await fixture(t);+ await b.publish("personal:U1", "PUBLISHED_BODY");+ for (const path of [+ "skill://missing/SKILL.md",+ "skill://source-helper/../SKILL.md",+ "skill://source-helper/.tree",+ "skill://../SKILL.md",+ "skill://source-helper//SKILL.md",+ "skill://source-helper/./SKILL.md",+ "skill://source-helper/references/../../secret",+ "skill://source-helper/%2e%2e/secret",+ ])+ assert.match(await b.turn(`!read ${path}`), /no file/, path);+ assert.equal(b.provisions(), 0);+});++test("published source follows scope shadowing and preserves sandbox-authored working copies", async (t) => {+ const b = await fixture(t);+ await b.publish("org:default-org", "ORG_BODY");+ const personal = await b.publish("personal:U1", "PERSONAL_BODY");+ assert.equal(await b.turn("!read skill://source-helper/SKILL.md"), "PERSONAL_BODY");+ assert.equal(b.provisions(), 0);+ await b.turn("!read skills/source-helper/SKILL.md");+ await b.turn("!write skills/source-helper/SKILL.md LOCAL_EDIT");+ assert.equal(await b.turn("!read skill://source-helper/SKILL.md"), "PERSONAL_BODY");+ assert.equal(await b.turn("!read skills/source-helper/SKILL.md"), "LOCAL_EDIT");+ await b.skills.archive(personal.id);+ assert.equal(await b.turn("!read skill://source-helper/SKILL.md"), "ORG_BODY");+});++test("a source-only read avoids sandbox work and a subsequent asset request materializes the current revision", async () => {+ const { createTurnSandboxes } = await import("../src/core/orchestrator/sandboxes.ts");+ const { createSkillMaterializer } = await import("../src/skills/materialize.ts");+ type TurnSandboxContext = import("../src/core/orchestrator/sandboxes.ts").TurnSandboxContext;+ type SkillResolution = import("../src/skills/skill-store.ts").SkillResolution;+ const files = new Map<string, string>();+ let provisions = 0;+ const sandboxIds: Array<string | undefined> = [];+ let resolution = {+ skill: {+ id: "s",+ scopeId: "personal:U1",+ manifest: {+ name: "source-helper",+ body: "BODY",+ files: [{ path: "references/example.txt", content: "v1" }],+ },+ },+ shadowed: [],+ } as unknown as SkillResolution;+ const handle = { id: "box", rootDir: "/workspace" };+ const turn = createTurnSandboxes({+ deps: {+ skills: { recordUse: async () => {} },+ sandboxResources: { get: async () => ({ ownerScopeId: "personal:U1" }) },+ sandbox: {+ provision: async (_layers: unknown, options?: { sandboxId?: string }) => {+ sandboxIds.push(options?.sandboxId);+ provisions++;+ return handle;+ },+ listDir: async () => [],+ removeDir: async () => {},+ readFile: async (_handle: unknown, path: string) => files.get(path) ?? null,+ writeFile: async (_handle: unknown, path: string, content: string) => {+ files.set(path, content);+ },+ },+ },+ input: { origin: { kind: "human" } },+ actor: { id: "U1" },+ session: { id: "s" },+ resolution: { layers: [{ scopeId: "personal:U1", mountPath: "", mode: "rw" }] },+ scopeId: "personal:U1",+ memoryScopeId: "personal:U1",+ turnSessionDir: "turn/s",+ turnFilesDir: "turn/s/t",+ connectorEnv: {},+ ownerEnvCredentialIds: [],+ credentialCutoverServices: [],+ visibleSkills: [resolution],+ visibleSkillsForTurn: async () => [resolution],+ skillMaterializer: createSkillMaterializer(),+ emitGapWork: () => {},+ perf: { credsMs: 0 },+ } as unknown as TurnSandboxContext);+ assert.equal((await turn.readSkill("skill://source-helper/SKILL.md")).content, "BODY");+ assert.equal(provisions, 0);+ assert.equal(files.size, 0);+ resolution = structuredClone(resolution);+ resolution.skill!.manifest.files![0]!.content = "v2";+ assert.equal((await turn.readSkill("skill://source-helper/references/example.txt")).content, "v2");+ await turn.ensureSkillTree("source-helper");+ assert.equal(provisions, 1);+ assert.equal(files.get("skills/source-helper/references/example.txt"), "v2");+ files.set("skills/source-helper/references/example.txt", "local edit");+ await turn.provision();+ assert.equal(files.get("skills/source-helper/references/example.txt"), "local edit");+ resolution.skill!.pack = { packId: "pack", commit: "c", upstreamName: "source-helper" };+ resolution.screenedBundles = [+ { packId: "pack", commit: "c", hash: "pack-hash", files: [{ path: "lib.txt", content: "PACK_RESOURCE" }] },+ ];+ await turn.ensureSkillTree(".packs", "resource-1");+ assert.deepEqual(sandboxIds, [undefined, "resource-1"]);+ assert.equal(files.get("skills/.packs/pack/lib.txt"), "PACK_RESOURCE");+});++test("pack assets remain readable and executable on later turns after source-only reads", async (t) => {+ const { computeBundleHash } = await import("../src/skills/skill-bundle-store.ts");+ const b = await fixture(t);+ const skill = await b.publish("personal:U1", "PACK_BODY", "source-pack");+ const files = [{ path: "example.sh", content: "printf PACK_ASSET" }];+ await b.skillBundles.put({ packId: "source-pack", commit: "c", files, hash: computeBundleHash(files) });+ assert.match(await b.turn("!read skill://source-helper/SKILL.md"), /skills\/\.packs\/source-pack/);+ assert.equal(b.provisions(), 0);+ assert.equal(await b.turn("!run sh skills/.packs/source-pack/example.sh"), "PACK_ASSET");+ assert.equal(await b.turn("!read skills/.packs/source-pack/example.sh"), "printf PACK_ASSET");+ await b.skills.archive(skill.id);+ assert.match(await b.turn("!read skills/.packs/source-pack/example.sh"), /no file/);+});