Skip to content

armgit / qm

Public Imported from GitHub
0

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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", asy
assert.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.ts
index 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 usa
assert.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())