Multiplayer agent harness for work.
Add per-scope pinned skills to the skills shortlist (#2386)
Joshua France4ad6a2c7a7fd
diff --git a/src/api/agent-api-catalog.ts b/src/api/agent-api-catalog.tsindex fd9fe43a4..d73d0881a 100644--- a/src/api/agent-api-catalog.ts+++ b/src/api/agent-api-catalog.ts@@ -558,6 +558,18 @@ const FAMILIES: AgentApiFamily[] = [{ method: "POST", path: "/v1/webhooks/:id/enable", summary: "re-enable a webhook" },],},+ {+ match: (m, p) => p === "/v1/pinned-skills" && (m === "GET" || m === "PUT"),+ routes: [+ { method: "GET", path: "/v1/pinned-skills", summary: "list the skills pinned to this conversation's scope" },+ {+ method: "PUT",+ path: "/v1/pinned-skills",+ summary:+ "replace this scope's pinned skills — body {names: string[]} in display order (max 6; [] clears); they always lead the per-turn skills shortlist. Personal pins apply to that person's DMs, channel pins to that channel. Live person turns only",+ },+ ],+ },{match: (m, p) => p === "/v1/soul" && (m === "POST" || m === "GET"),when: () => false,diff --git a/src/api/routes/surface.ts b/src/api/routes/surface.tsindex 637ce18ca..a08640fda 100644--- a/src/api/routes/surface.ts+++ b/src/api/routes/surface.ts@@ -18,6 +18,7 @@ import {} from "../../model/pi-models.ts";import { builtInModelCatalog, selectableCatalogForHarness, selectableModelCatalog } from "../../model/model-catalog.ts";import { errMessage } from "../../util/errors.ts";+import { parsePinnedSkills } from "../../skills/materialize.ts";import { renderAgentApis } from "../agent-api-catalog.ts";import { mintCapabilityToken, CAPABILITY_TTL_MS } from "../../auth/capability-token.ts";import { contentTypeWithUtf8Charset, pipeToResponse, sendJson } from "../http.ts";@@ -1318,6 +1319,34 @@ export async function postSoul(ctx: ApiCtx): Promise<void> {}}+async function getPinnedSkills(ctx: ApiCtx): Promise<void> {+ if (!ctx.deps.config) return sendJson(ctx.res, 404, { error: "not_found" });+ const target = await runtimeTarget(ctx);+ if (!target) return sendJson(ctx.res, 403, { error: "forbidden" });+ return sendJson(ctx.res, 200, {+ scopeId: target.scope,+ names: await ctx.deps.config.getPinnedSkillsDurable(target.scope),+ });+}++async function putPinnedSkills(ctx: ApiCtx): Promise<void> {+ if (!ctx.deps.config || !isObj(ctx.body)) return sendJson(ctx.res, 400, { error: "bad_request" });+ if (ctx.capability && !livePersonCapability(ctx.capability))+ return sendJson(ctx.res, 403, { error: "live_actor_required" });+ const target = await runtimeTarget(ctx);+ if (!target) return sendJson(ctx.res, 403, { error: "forbidden" });+ const parsed = parsePinnedSkills(ctx.body.names);+ if ("error" in parsed) return sendJson(ctx.res, 400, { error: "bad_request", message: parsed.error });+ await ctx.deps.config.setPinnedSkills(target.scope, parsed.value);+ audit(ctx.deps, {+ principalId: target.actorId,+ action: "pinned-skills.update",+ resource: `pinned-skills: ${parsed.value.join(", ")}`,+ scopeLabel: target.scope,+ });+ return sendJson(ctx.res, 200, { scopeId: target.scope, names: parsed.value });+}+export const surfaceRoutes: ReadonlyArray<Route<ApiCtx>> = [...sessionSharingRoutes,...suggestedActivityRoutes,@@ -1383,4 +1412,6 @@ export const surfaceRoutes: ReadonlyArray<Route<ApiCtx>> = [{ method: "PUT", path: "/v1/channel-header-pin", auth: "either", handle: putChannelHeaderPin },{ method: "GET", path: "/v1/soul", auth: "either", handle: getSoul },{ method: "POST", path: "/v1/soul", auth: "either", handle: postSoul },+ { method: "GET", path: "/v1/pinned-skills", auth: "either", handle: getPinnedSkills },+ { method: "PUT", path: "/v1/pinned-skills", auth: "either", handle: putPinnedSkills },];diff --git a/src/core/orchestrator.ts b/src/core/orchestrator.tsindex 228bdcee0..c28d3cd1a 100644--- a/src/core/orchestrator.ts+++ b/src/core/orchestrator.ts@@ -154,7 +154,7 @@ import {selectOverheardToImport,type OverheardEntryPayload,} from "../harness/replay.ts";-import { errMessage, reportFailure, swallow, swallowAs } from "../util/errors.ts";+import { errMessage, reportFailure, reportFailureAs, swallow, swallowAs } from "../util/errors.ts";import { isObj } from "../util/objects.ts";import { absoluteAppLinks, jsonbSafeStringify } from "../util/text.ts";import {@@ -2972,11 +2972,15 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {? [p.name]: [];});+ const pinnedSkills = deps.config+ ? await deps.config.getPinnedSkillsDurable(scopeId).catch(reportFailureAs("orchestrator: pinned skills", []))+ : [];turnContextBlocks["Skills"] = skillsIndex(nativeSkills,[scopeId, resolution.orgScopeId],input.text,usedSkills,+ pinnedSkills,);const turnEnvironmentContents = [manifest,diff --git a/src/harness/agent-tools.ts b/src/harness/agent-tools.tsindex ee681b09a..a1b7e4e90 100644--- a/src/harness/agent-tools.ts+++ b/src/harness/agent-tools.ts@@ -2938,7 +2938,9 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):"context it is shared by ALL of that person's sessions, not tied to the session that " +"wrote it. Never store session pins or 'for this session' notes here: ALL pinning goes " +"through the pins self-API (POST /v1/pins), which routes by context — the session's own " +- "pins in the web UI, native pinning in Slack. `edit` swaps one exact passage `old` for `new` " ++ "pins in the web UI, native pinning in Slack. To keep a skill in this scope's per-turn skills shortlist, " ++ 'pin it instead of writing guidance: PUT $AGENT_API_URL/v1/pinned-skills with header "x-agent-capability: $AGENT_API_TOKEN" ' ++ 'and body {"names": [...]}, the full list. `edit` swaps one exact passage `old` for `new` ' +"and fails unless `old` appears exactly once in that scope's guidance; prefer it for small changes. " +"`replace` REPLACES that scope's entire guidance with `content` — include everything that " +"should remain. Org-wide policy is always layered above and " +diff --git a/src/resolution/config-store.ts b/src/resolution/config-store.tsindex 102d13960..9899ebc29 100644--- a/src/resolution/config-store.ts+++ b/src/resolution/config-store.ts@@ -110,6 +110,10 @@ export interface PersistedAckEmoji {scopeId: ScopeId;names: string[];}+export interface PersistedPinnedSkills {+ scopeId: ScopeId;+ names: string[];+}export interface PersistedSlackEmojiCatalog {scopeId: ScopeId;emoji: Record<string, string>;@@ -247,6 +251,8 @@ export interface ScopedConfigStore {getAckEmoji(id: ScopeId): string[] | null;setAckEmoji(id: ScopeId, names: string[] | null): void;getAckEmojiDurable(id: ScopeId): Promise<string[] | null>;+ getPinnedSkillsDurable(id: ScopeId): Promise<string[]>;+ setPinnedSkills(id: ScopeId, names: string[]): Promise<void>;setSlackEmojiCatalog(id: ScopeId, emoji: Record<string, string>): void;getSlackEmojiCatalogDurable(id: ScopeId): Promise<PersistedSlackEmojiCatalog | null>;getPeopleDirectoryUrl(id: ScopeId): string | null;@@ -295,6 +301,7 @@ export function createMemoryConfigStore(webuiModels?: DurableMap<PersistedWebuiModels>;peopleDirectoryUrls?: DurableMap<PersistedPeopleDirectoryUrl>;ackEmoji?: DurableMap<PersistedAckEmoji>;+ pinnedSkills?: DurableMap<PersistedPinnedSkills>;slackEmojiCatalog?: DurableMap<PersistedSlackEmojiCatalog>;branding?: DurableMap<PersistedBranding>;browseMaxSteps?: DurableMap<PersistedBrowseMaxSteps>;@@ -350,6 +357,7 @@ export function createMemoryConfigStore(const webuiModelStore = opts.webuiModels ?? createMemoryMap<PersistedWebuiModels>();const peopleDirectoryUrlStore = opts.peopleDirectoryUrls ?? createMemoryMap<PersistedPeopleDirectoryUrl>();const ackEmojiStore = opts.ackEmoji ?? createMemoryMap<PersistedAckEmoji>();+ const pinnedSkillsStore = opts.pinnedSkills ?? createMemoryMap<PersistedPinnedSkills>();const slackEmojiCatalogStore = opts.slackEmojiCatalog ?? createMemoryMap<PersistedSlackEmojiCatalog>();const brandingStore = opts.branding ?? createMemoryMap<PersistedBranding>();const browseMaxStepsStore = opts.browseMaxSteps ?? createMemoryMap<PersistedBrowseMaxSteps>();@@ -1049,6 +1057,11 @@ export function createMemoryConfigStore(if (pending) await pending;return (await ackEmojiStore.get(id))?.names ?? null;},+ getPinnedSkillsDurable: async (id) => (await pinnedSkillsStore.get(id))?.names ?? [],+ setPinnedSkills: (id, names) =>+ writeQueue(`pinnedSkills:${id}`, () =>+ names.length ? pinnedSkillsStore.put(id, { scopeId: id, names }) : pinnedSkillsStore.delete(id),+ ),setSlackEmojiCatalog(id, emoji) {persist(`slackEmojiCatalog:${id}`, "slack emoji catalog", () =>slackEmojiCatalogStore.put(id, { scopeId: id, emoji, updatedAt: Date.now() }),diff --git a/src/skills/materialize.ts b/src/skills/materialize.tsindex 188c9274d..a5dca0501 100644--- a/src/skills/materialize.ts+++ b/src/skills/materialize.ts@@ -2,7 +2,7 @@ import { CapabilityUnsupportedError, type Sandbox, type SandboxHandle } from "..import { safeSkillFilePath, type SkillFile, type SkillResolution } from "./skill-store.ts";import type { SkillBundle } from "./skill-bundle-store.ts";import { swallow } from "../util/errors.ts";-import { assertSafeSkillName } from "./skill-name.ts";+import { assertSafeSkillName, isSafeSkillName } from "./skill-name.ts";import type { ScopeId } from "../types.ts";export const SKILLS_DIR = "skills";@@ -134,15 +134,31 @@ export function rankedSkills(.map(({ entry }) => entry);}+const SHORTLIST_SIZE = 12;+const MAX_PINNED_SKILLS = SHORTLIST_SIZE / 2;++export function parsePinnedSkills(raw: unknown): { value: string[] } | { error: string } {+ if (!Array.isArray(raw) || !raw.every((name) => typeof name === "string"))+ return { error: "pinned skills require { names: string[] } (an empty list clears them)" };+ const names = [...new Set(raw.map((name) => name.trim()).filter(Boolean))];+ const bad = names.find((name) => !isSafeSkillName(name));+ if (bad) return { error: `not a valid skill name: ${bad}` };+ if (names.length > MAX_PINNED_SKILLS) return { error: `at most ${MAX_PINNED_SKILLS} skills can be pinned` };+ return { value: names };+}+export function skillsIndex(resolved: SkillResolution[],provenanceScopes: readonly ScopeId[] = [],query = "",usedNames: readonly string[] = [],+ pinnedNames: readonly string[] = [],): string {const provenance = new Set(provenanceScopes);const ranked = rankedSkills(resolved, query, usedNames);- const items = ranked.slice(0, 12);+ const byName = new Map(ranked.map((r) => [r.skill!.manifest.name, r]));+ const pinned = pinnedNames.flatMap((name) => byName.get(name) ?? []);+ const items = [...new Set([...pinned, ...ranked])].slice(0, SHORTLIST_SIZE);if (!items.length) return "";const lines = items.map((r) => {const m = r.skill!.manifest;diff --git a/src/wiring.ts b/src/wiring.tsindex a3aab8852..e7fd78a13 100644--- a/src/wiring.ts+++ b/src/wiring.ts@@ -107,6 +107,7 @@ import {type PersistedWebuiModels,type PersistedPeopleDirectoryUrl,type PersistedAckEmoji,+ type PersistedPinnedSkills,type PersistedSlackEmojiCatalog,type PersistedBranding,type PersistedBrowseMaxSteps,@@ -704,6 +705,7 @@ export function buildApp(webuiModels: artifactMap<PersistedWebuiModels>("webui_model_configs"),peopleDirectoryUrls: artifactMap<PersistedPeopleDirectoryUrl>("people_directory_urls"),ackEmoji: artifactMap<PersistedAckEmoji>("ack_emoji"),+ pinnedSkills: artifactMap<PersistedPinnedSkills>("pinned_skills"),slackEmojiCatalog: artifactMap<PersistedSlackEmojiCatalog>("slack_emoji_catalog"),branding: artifactMap<PersistedBranding>("branding_configs"),browseMaxSteps: artifactMap<PersistedBrowseMaxSteps>("browse_max_steps_configs"),diff --git a/test/capability-routes.test.ts b/test/capability-routes.test.tsindex 708c0da3b..2eea0ea8a 100644--- a/test/capability-routes.test.ts+++ b/test/capability-routes.test.ts@@ -362,6 +362,36 @@ describe("capability-token control plane (crons + webhooks + SOUL)", () => {);});+ it("sets pinned skills on the live speaker's own scope only", async () => {+ const put = async (body: unknown, token: string) =>+ fetch(`${base}/v1/pinned-skills`, {+ method: "PUT",+ headers: { "content-type": "application/json", "x-agent-capability": token },+ body: JSON.stringify(body),+ });+ const live = { liveActor: true };+ const mine = await put(+ { names: ["voice", "drafts"], scopeId: "org:default-org" },+ await capFor("U3", undefined, live),+ );+ assert.equal(mine.status, 200);+ assert.deepEqual(await built.config.getPinnedSkillsDurable(scopeId("personal", "U3")), ["voice", "drafts"]);+ assert.deepEqual(await built.config.getPinnedSkillsDurable(scopeId("org", "default-org")), []);+ const read = await get("/v1/pinned-skills", { "x-agent-capability": await capFor("U3") });+ assert.deepEqual(((await read.json()) as { names: string[] }).names, ["voice", "drafts"]);++ assert.equal((await put({ names: ["voice"] }, await capChannel("U8", live))).status, 200);+ assert.deepEqual(await built.config.getPinnedSkillsDurable(scopeId("channel", "C")), ["voice"]);++ assert.equal((await put({ names: ["x"] }, await capFor("U3"))).status, 403, "background turns cannot change pins");+ assert.equal((await put({}, await capFor("U3", undefined, live))).status, 400, "a missing list does not clear");+ assert.equal((await put({ names: ["x"] }, await capFor("U3", scopeId("org", "default-org"), live))).status, 403);+ assert.deepEqual(await built.config.getPinnedSkillsDurable(scopeId("personal", "U3")), ["voice", "drafts"]);++ assert.equal((await put({ names: [] }, await capFor("U3", undefined, live))).status, 200);+ assert.deepEqual(await built.config.getPinnedSkillsDurable(scopeId("personal", "U3")), []);+ });+it("updates only the caller's OWN personal SOUL, ignoring body scope/actor", async () => {const orgVerBefore = built.config.soulVersion(scopeId("org", "default-org"));const res = await post(diff --git a/test/skills-callable.test.ts b/test/skills-callable.test.tsindex 01ab64f61..66a8c9fd0 100644--- a/test/skills-callable.test.ts+++ b/test/skills-callable.test.ts@@ -63,6 +63,46 @@ test("a published personal skill is advertised and loads in the owner's DM", asyassert.match(read.reply ?? "", /Step 1: gather/);});+test("a skill pinned to the person's scope is listed in their DM shortlist even when the message doesn't mention it", async () => {+ const { app, skills, config } = freshApp();+ for (let i = 0; i < 13; i++) {+ const sk = await skills.create({+ scopeId: scopeId("personal", "U1"),+ manifest: {+ name: `aa-filler-${i}`,+ description: "filler",+ requiredCapabilities: [],+ body: "# filler",+ },+ createdBy: "U1",+ });+ await skills.review(sk.id, "reviewer-1", []);+ await skills.publish(sk.id);+ }+ const sk = await skills.create({+ scopeId: scopeId("personal", "U1"),+ manifest: { name: "zz-voice", description: "write in my voice", requiredCapabilities: [], body: "# voice" },+ createdBy: "U1",+ });+ await skills.review(sk.id, "reviewer-1", []);+ await skills.publish(sk.id);+ const shortlist = async (thread: string) =>+ (+ await app.turn({+ surface: "test",+ actor,+ conversation: { kind: "dm", threadRef: thread },+ text: "!sysprompt",+ } as TurnRequest)+ ).reply ?? "";++ assert.doesNotMatch(await shortlist("dm:U1:p1"), /zz-voice/);+ await config.setPinnedSkills(scopeId("personal", "U1"), ["zz-voice", "not-a-real-skill"]);+ const pinned = await shortlist("dm:U1:p2");+ assert.match(pinned, /Showing 12 of \d+ available skills\.[^\n]*\n- \*\*zz-voice\*\*/);+ assert.doesNotMatch(pinned, /not-a-real-skill/);+});+test("a channel session does NOT see a personal skill (scope boundary)", async () => {const { app, skills } = freshApp();await publishPersonalSkill(skills);diff --git a/test/skills-materialize.test.ts b/test/skills-materialize.test.tsindex e0ff49f4b..8f1fac46b 100644--- a/test/skills-materialize.test.ts+++ b/test/skills-materialize.test.ts@@ -6,6 +6,7 @@ import { CapabilityUnsupportedError, type Sandbox, type SandboxHandle } from "..import type { SkillFile, SkillResolution } from "../src/skills/skill-store.ts";import {materializeSkillTree,+ parsePinnedSkills,rankedSkills,renderSkillBody,safeSkillDirName,@@ -179,6 +180,35 @@ test("skill shortlist favors relevant and visibly used skills without global usaassert.equal(skillsIndex([{ skill: null, shadowed: [] }]), "");});+test("pinned skills lead the shortlist regardless of the message and count toward the cap", () => {+ const skills = Array.from({ length: 20 }, (_, i) => {+ const r = res(`skill-${String(i).padStart(2, "0")}`, "body");+ r.skill!.manifest.description = i === 5 ? "drafting telescope notes" : "something else";+ return r;+ });+ const names = (index: string) => [...index.matchAll(/\*\*([^*]+)\*\*/g)].map((m) => m[1]);++ const unpinned = names(skillsIndex(skills, [], "telescope"));+ assert.ok(!unpinned.includes("skill-19"), "a non-matching skill falls past the cap without a pin");++ const index = skillsIndex(skills, [], "telescope", [], ["skill-19", "missing-skill", "skill-18"]);+ assert.match(index, /Showing 12 of 20/);+ const shown = names(index);+ assert.deepEqual(+ shown.slice(0, 2),+ ["skill-19", "skill-18"],+ "pins lead in their configured order; unknown names are ignored",+ );+ assert.equal(shown[2], "skill-05", "ranking resumes after the pins");+ assert.equal(shown.length, 12);+ assert.equal(new Set(shown).size, 12, "a pinned skill is not listed twice");++ assert.deepEqual(parsePinnedSkills([" voice ", "voice", "drafts"]), { value: ["voice", "drafts"] });+ assert.ok("error" in parsePinnedSkills(undefined), "a missing list is an error, not a clear");+ assert.ok("error" in parsePinnedSkills(["../etc"]));+ assert.ok("error" in parsePinnedSkills(["a", "b", "c", "d", "e", "f", "g"]), "pins leave room for ranked skills");+});+test("a natural-language Gmail request keeps its relevant bundled skill in the shortlist", () => {const entries = readdirSync(new URL("../skills-seed/", import.meta.url), { withFileTypes: true }).filter((entry) => entry.isDirectory())