runline 0.30.0 → 0.31.0

package/dist/plugins/linear/src/initiatives.js

@@ -1,5 +1,5 @@
 import * as t from "typebox";
-import { bindGetAction, bindListAction, gql, INITIATIVE_FIELDS, key, requireUnscoped, } from "./shared.js";
+import { bindGetAction, bindListAction, gql, INITIATIVE_FIELDS, key, requireUnscoped, withScopedNote, } from "./shared.js";
 export function registerInitiativeActions(rl) {
     const listAction = bindListAction(rl);
     const getAction = bindGetAction(rl);
@@ -7,7 +7,7 @@ export function registerInitiativeActions(rl) {
     getAction("initiative.get", "Get an initiative by ID or slug.", "initiative", INITIATIVE_FIELDS);
     rl.registerAction("initiative.create", {
         access: "write",
-        description: "Create an initiative. Status: Planned | Active | Completed.",
+        description: withScopedNote("Create an initiative. Status: Planned | Active | Completed."),
         inputSchema: t.Object({
             name: t.String({ description: "The name of the initiative" }),
             description: t.Optional(t.String({ description: "The description of the initiative" })),
@@ -41,7 +41,7 @@ export function registerInitiativeActions(rl) {
     });
     rl.registerAction("initiative.update", {
         access: "write",
-        description: "Update an initiative.",
+        description: withScopedNote("Update an initiative."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the initiative to update",
@@ -79,7 +79,7 @@ export function registerInitiativeActions(rl) {
     });
     rl.registerAction("initiative.delete", {
         access: "write",
-        description: "Trash an initiative.",
+        description: withScopedNote("Trash an initiative."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the initiative to delete",
@@ -93,7 +93,7 @@ export function registerInitiativeActions(rl) {
     });
     rl.registerAction("initiative.addProject", {
         access: "write",
-        description: "Associate a project with an initiative. Use this action for project-to-initiative linking; project.update does not accept initiativeId. Verify with initiative.get or the returned initiative.projects list.",
+        description: withScopedNote("Associate a project with an initiative. Use this action for project-to-initiative linking; project.update does not accept initiativeId. Verify with initiative.get or the returned initiative.projects list."),
         inputSchema: t.Object({
             initiativeId: t.String({
                 description: "The identifier of the initiative",
@@ -114,7 +114,7 @@ export function registerInitiativeActions(rl) {
     });
     rl.registerAction("initiative.removeProject", {
         access: "write",
-        description: "Remove a project from an initiative. Pass the link id returned by initiative.addProject, then verify with initiative.get.",
+        description: withScopedNote("Remove a project from an initiative. Pass the link id returned by initiative.addProject, then verify with initiative.get."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the initiativeToProject to delete",

package/dist/plugins/linear/src/issues.js

@@ -68,14 +68,14 @@ export function registerIssueActions(rl) {
         }),
         async execute(input, ctx) {
             const fields = { ...input };
-            fields.labelIds = ensureScopeLabelsOnCreateOrReplace(ctx, fields.labelIds);
+            fields.labelIds = await ensureScopeLabelsOnCreateOrReplace(ctx, fields.labelIds);
             const data = await gql(key(ctx), `mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { ${ISSUE_FIELDS} } } }`, { input: fields });
             return data.issueCreate?.issue;
         },
     });
     rl.registerAction("issue.get", {
         access: "read",
-        description: "Get an issue by ID or identifier (e.g. 'THE-154')",
+        description: "Get an issue by ID or identifier (e.g. 'THE-154').",
         inputSchema: t.Object({
             issueId: t.String({
                 description: "Required parameter name. Pass either the Linear issue UUID or issue identifier, e.g. 'THE-154'.",
@@ -84,14 +84,14 @@ export function registerIssueActions(rl) {
         async execute(input, ctx) {
             const data = await gql(key(ctx), `query($id: String!) { issue(id: $id) { ${ISSUE_FIELDS} } }`, { id: input.issueId });
             const issue = data.issue;
-            if (!issueHasScope(ctx, issue))
+            if (!(await issueHasScope(ctx, issue)))
                 throw new Error("Linear issue is not available to this scoped connection");
             return issue;
         },
     });
     rl.registerAction("issue.list", {
         access: "read",
-        description: "List issues. Pass `filter` for state/label/project/etc. Default hides archived.",
+        description: "List issues. teamId and assigneeId are convenience filters; use `filter` for anything else - assignee { assignee: { isMe: { eq: true } } }, cycle { cycle: { id: { eq: 'cycle-id' } } }, open work { state: { type: { nin: ['completed','canceled'] } } }. Default hides archived.",
         inputSchema: t.Object({
             ...LIST_INPUT_SCHEMA,
             teamId: t.Optional(t.String({ description: "Convenience: filter by team" })),
@@ -105,7 +105,7 @@ export function registerIssueActions(rl) {
                 merged.team = { id: { eq: opts.teamId } };
             if (opts.assigneeId)
                 merged.assignee = { id: { eq: opts.assigneeId } };
-            const filter = mergeIssueScopeFilter(ctx, Object.keys(merged).length > 0 ? merged : undefined);
+            const filter = await mergeIssueScopeFilter(ctx, Object.keys(merged).length > 0 ? merged : undefined);
             const { argsDecl, argsCall, vars } = buildConnArgs({ ...opts, filter }, "IssueFilter");
             const data = await gql(key(ctx), `query${argsDecl} { issues${argsCall} { nodes { ${ISSUE_LITE} } pageInfo { hasNextPage endCursor } } }`, vars);
             const conn = data.issues;
@@ -169,9 +169,9 @@ export function registerIssueActions(rl) {
             const { issueId, ...fields } = input;
             await assertIssueInScope(ctx, String(issueId));
             if (fields.removedLabelIds)
-                forbidScopeLabelRemoval(ctx, fields.removedLabelIds);
+                await forbidScopeLabelRemoval(ctx, fields.removedLabelIds);
             if (fields.labelIds)
-                fields.labelIds = ensureScopeLabelsOnCreateOrReplace(ctx, fields.labelIds);
+                fields.labelIds = await ensureScopeLabelsOnCreateOrReplace(ctx, fields.labelIds);
             const data = await gql(key(ctx), `mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { ${ISSUE_FIELDS} } } }`, { id: issueId, input: fields });
             return data.issueUpdate?.issue;
         },
@@ -246,7 +246,7 @@ export function registerIssueActions(rl) {
         }`, {
                 term: opts.term,
                 first: opts.limit ?? 50,
-                filter: mergeIssueScopeFilter(ctx, opts.filter) ?? null,
+                filter: (await mergeIssueScopeFilter(ctx, opts.filter)) ?? null,
                 includeComments: opts.includeComments ?? null,
                 includeArchived: opts.includeArchived ?? null,
                 teamId: opts.teamId ?? null,
@@ -281,7 +281,7 @@ export function registerIssueActions(rl) {
         async execute(input, ctx) {
             const { issueId, labelId } = input;
             await assertIssueInScope(ctx, issueId);
-            forbidScopeLabelRemoval(ctx, labelId);
+            await forbidScopeLabelRemoval(ctx, labelId);
             const data = await gql(key(ctx), `mutation($id: String!, $labelId: String!) { issueRemoveLabel(id: $id, labelId: $labelId) { success } }`, { id: issueId, labelId });
             return data.issueRemoveLabel;
         },

package/dist/plugins/linear/src/labels.js

@@ -1,5 +1,5 @@
 import * as t from "typebox";
-import { bindGetAction, bindListAction, gql, key, LABEL_FIELDS, requireUnscoped, } from "./shared.js";
+import { bindGetAction, bindListAction, gql, key, LABEL_FIELDS, requireUnscoped, withScopedNote, } from "./shared.js";
 export function registerLabelActions(rl) {
     const listAction = bindListAction(rl);
     const getAction = bindGetAction(rl);
@@ -7,7 +7,7 @@ export function registerLabelActions(rl) {
     getAction("label.get", "Get a label by ID.", "issueLabel", LABEL_FIELDS);
     rl.registerAction("label.create", {
         access: "write",
-        description: "Create a label. Omit teamId for a workspace-level label.",
+        description: withScopedNote("Create a label. Omit teamId for a workspace-level label."),
         inputSchema: t.Object({
             name: t.String({ description: "The name of the label" }),
             teamId: t.Optional(t.String({
@@ -38,7 +38,7 @@ export function registerLabelActions(rl) {
     });
     rl.registerAction("label.update", {
         access: "write",
-        description: "Update a label.",
+        description: withScopedNote("Update a label."),
         inputSchema: t.Object({
             id: t.String({ description: "The identifier of the label to update" }),
             name: t.Optional(t.String({ description: "The name of the label" })),
@@ -62,7 +62,7 @@ export function registerLabelActions(rl) {
     });
     rl.registerAction("label.delete", {
         access: "write",
-        description: "Delete a label.",
+        description: withScopedNote("Delete a label."),
         inputSchema: t.Object({
             id: t.String({ description: "The identifier of the label to delete" }),
         }),
@@ -74,7 +74,7 @@ export function registerLabelActions(rl) {
     });
     rl.registerAction("label.retire", {
         access: "write",
-        description: "Retire a label. Retired labels remain visible but cannot be applied to new issues.",
+        description: withScopedNote("Retire a label. Retired labels remain visible but cannot be applied to new issues."),
         inputSchema: t.Object({
             id: t.String({ description: "The identifier of the label to retire" }),
         }),
@@ -86,7 +86,7 @@ export function registerLabelActions(rl) {
     });
     rl.registerAction("label.restore", {
         access: "write",
-        description: "Restore a previously retired label.",
+        description: withScopedNote("Restore a previously retired label."),
         inputSchema: t.Object({
             id: t.String({ description: "The identifier of the label to restore" }),
         }),

package/dist/plugins/linear/src/organization.js

@@ -1,9 +1,9 @@
 import * as t from "typebox";
-import { gql, key, ORG_FIELDS, requireUnscoped } from "./shared.js";
+import { gql, key, ORG_FIELDS, requireUnscoped, withScopedNote, } from "./shared.js";
 export function registerOrganizationActions(rl) {
     rl.registerAction("org.get", {
         access: "read",
-        description: "Get the authenticated workspace.",
+        description: withScopedNote("Get the authenticated workspace."),
         inputSchema: t.Object({}),
         async execute(_input, ctx) {
             requireUnscoped(ctx, "org.get");

package/dist/plugins/linear/src/projects.js

@@ -1,5 +1,5 @@
 import * as t from "typebox";
-import { bindGetAction, bindListAction, gql, key, MILESTONE_FIELDS, PROJECT_FIELDS, PROJECT_UPDATE_FIELDS, requireUnscoped, } from "./shared.js";
+import { bindGetAction, bindListAction, gql, key, MILESTONE_FIELDS, PROJECT_FIELDS, PROJECT_UPDATE_FIELDS, requireUnscoped, withScopedNote, } from "./shared.js";
 export function registerProjectActions(rl) {
     const listAction = bindListAction(rl);
     const getAction = bindGetAction(rl);
@@ -7,7 +7,7 @@ export function registerProjectActions(rl) {
     getAction("project.get", "Get a project by ID or slug.", "project", PROJECT_FIELDS);
     rl.registerAction("project.create", {
         access: "write",
-        description: "Create a project. teamIds is required.",
+        description: withScopedNote("Create a project. teamIds is required."),
         inputSchema: t.Object({
             name: t.String({ description: "The name of the project" }),
             teamIds: t.Array(t.Unknown(), {
@@ -68,7 +68,7 @@ export function registerProjectActions(rl) {
     });
     rl.registerAction("project.update", {
         access: "write",
-        description: "Update a project.",
+        description: withScopedNote("Update a project."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the project to update (UUID or slug)",
@@ -126,7 +126,7 @@ export function registerProjectActions(rl) {
     });
     rl.registerAction("project.delete", {
         access: "write",
-        description: "Trash (soft-delete) a project. Restorable via project.unarchive.",
+        description: withScopedNote("Trash (soft-delete) a project. Restorable via project.unarchive."),
         inputSchema: t.Object({
             id: t.String({ description: "The identifier of the project to delete" }),
         }),
@@ -138,7 +138,7 @@ export function registerProjectActions(rl) {
     });
     rl.registerAction("project.unarchive", {
         access: "write",
-        description: "Restore a previously trashed or archived project.",
+        description: withScopedNote("Restore a previously trashed or archived project."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the project to restore (UUID or slug)",
@@ -152,7 +152,7 @@ export function registerProjectActions(rl) {
     });
     rl.registerAction("project.search", {
         access: "read",
-        description: "Search projects by text. Rate-limited to 30 req/min.",
+        description: withScopedNote("Search projects by text. Rate-limited to 30 req/min."),
         inputSchema: t.Object({
             term: t.String({ description: "Search string to look for" }),
             limit: t.Optional(t.Number({
@@ -185,7 +185,7 @@ export function registerProjectActions(rl) {
     getAction("milestone.get", "Get a project milestone by ID.", "projectMilestone", MILESTONE_FIELDS);
     rl.registerAction("milestone.create", {
         access: "write",
-        description: "Create a project milestone.",
+        description: withScopedNote("Create a project milestone."),
         inputSchema: t.Object({
             projectId: t.String({
                 description: "Related project for the project milestone",
@@ -213,7 +213,7 @@ export function registerProjectActions(rl) {
     });
     rl.registerAction("milestone.update", {
         access: "write",
-        description: "Update a project milestone.",
+        description: withScopedNote("Update a project milestone."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the project milestone to update",
@@ -242,7 +242,7 @@ export function registerProjectActions(rl) {
     });
     rl.registerAction("milestone.delete", {
         access: "write",
-        description: "Delete a project milestone.",
+        description: withScopedNote("Delete a project milestone."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the project milestone to delete",
@@ -258,7 +258,7 @@ export function registerProjectActions(rl) {
     listAction("projectUpdate.list", "List project updates.", "projectUpdates", "ProjectUpdateFilter", PROJECT_UPDATE_FIELDS);
     rl.registerAction("projectUpdate.create", {
         access: "write",
-        description: "Post a status update on a project.",
+        description: withScopedNote("Post a status update on a project."),
         inputSchema: t.Object({
             projectId: t.String({
                 description: "The project to associate the project update with",
@@ -285,7 +285,7 @@ export function registerProjectActions(rl) {
     });
     rl.registerAction("projectUpdate.update", {
         access: "write",
-        description: "Update a project status update.",
+        description: withScopedNote("Update a project status update."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the project update to update",
@@ -310,7 +310,7 @@ export function registerProjectActions(rl) {
     });
     rl.registerAction("projectUpdate.archive", {
         access: "write",
-        description: "Archive a project status update.",
+        description: withScopedNote("Archive a project status update."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the project update to archive",

package/dist/plugins/linear/src/shared.js

@@ -1,10 +1,12 @@
+import { createHash } from "node:crypto";
 import * as t from "typebox";
+import { authedFetch } from "../../_shared/authedFetch.js";
 const GQL_URL = "https://api.linear.app/graphql";
 export async function gql(apiKey, query, variables) {
     const body = { query };
     if (variables)
         body.variables = variables;
-    const res = await fetch(GQL_URL, {
+    const res = await authedFetch(GQL_URL, {
         method: "POST",
         headers: { Authorization: apiKey, "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -19,7 +21,11 @@ export async function gql(apiKey, query, variables) {
 export function key(ctx) {
     return ctx.connection.config.apiKey;
 }
-export function scopeLabelIds(ctx) {
+/**
+ * The configured scope values, verbatim. Each is either a label UUID or a
+ * label name — `resolveScopeLabelIds` turns the latter into the former.
+ */
+export function scopeLabelValues(ctx) {
     const raw = ctx.connection.config.scopeLabelIds;
     if (Array.isArray(raw))
         return raw
@@ -33,11 +39,115 @@ export function scopeLabelIds(ctx) {
         .map((s) => s.trim())
         .filter(Boolean);
 }
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * The workspace's labels, per API key. Linear rejects a non-UUID in
+ * `labels: { id: { in: [...] } }` with "each value in in must be a UUID",
+ * so a human-written scope value like `requester:yosi` breaks every issue
+ * query (SHFT-1644) unless it is resolved to an id first. The directory is
+ * fetched once per key and re-read on a miss, so a label created later
+ * still resolves.
+ *
+ * Keyed by digest, so a long-lived Map never holds the API key itself.
+ */
+const labelDirectories = new Map();
+const directoryKey = (apiKey) => createHash("sha256").update(apiKey).digest("hex");
+async function fetchLabelDirectory(apiKey) {
+    const byName = new Map();
+    let after = null;
+    for (;;) {
+        const data = await gql(apiKey, `query($after: String) { issueLabels(first: 250, after: $after) { nodes { id name team { key } } pageInfo { hasNextPage endCursor } } }`, { after });
+        const conn = data.issueLabels;
+        for (const node of conn?.nodes ?? []) {
+            const name = String(node.name);
+            const team = node.team;
+            const entry = {
+                id: String(node.id),
+                name,
+                teamKey: typeof team?.key === "string" ? team.key : null,
+            };
+            const lookup = name.toLowerCase();
+            const existing = byName.get(lookup);
+            if (existing)
+                existing.push(entry);
+            else
+                byName.set(lookup, [entry]);
+        }
+        const pageInfo = conn?.pageInfo;
+        if (!pageInfo?.hasNextPage)
+            break;
+        const next = String(pageInfo.endCursor);
+        // A cursor that does not advance would page forever; stop instead.
+        if (next === after)
+            break;
+        after = next;
+    }
+    return byName;
+}
+function labelDirectory(apiKey, { refresh = false } = {}) {
+    const cacheKey = directoryKey(apiKey);
+    const cached = refresh ? undefined : labelDirectories.get(cacheKey);
+    if (cached)
+        return cached;
+    const pending = fetchLabelDirectory(apiKey);
+    labelDirectories.set(cacheKey, pending);
+    // A failed lookup must not be cached as the answer for this key.
+    pending.catch(() => {
+        if (labelDirectories.get(cacheKey) === pending)
+            labelDirectories.delete(cacheKey);
+    });
+    return pending;
+}
+function unknownLabelError(value) {
+    return new Error(`Linear scope label "${value}" is neither a label UUID nor the name of a label in this workspace. ` +
+        `Set scopeLabelIds (LINEAR_SCOPE_LABEL_IDS) to label UUIDs or exact label names, or unset it for full access.`);
+}
+/**
+ * Label names are not unique in Linear: every team may own a `bug` alongside
+ * a workspace one, and a case-insensitive match widens that further. Picking
+ * whichever paginated last would scope the connection to a label nobody
+ * chose — and a scope that silently binds to the wrong label shows the agent
+ * issues it was never meant to read. An ambiguous name is refused instead,
+ * with the candidates to choose between.
+ */
+function ambiguousLabelError(value, matches) {
+    const candidates = matches
+        .map((m) => `${m.teamKey ? `team ${m.teamKey}` : "workspace"} "${m.name}" → ${m.id}`)
+        .join("; ");
+    return new Error(`Linear scope label "${value}" is ambiguous: ${matches.length} labels share that name (${candidates}). ` +
+        `Set scopeLabelIds (LINEAR_SCOPE_LABEL_IDS) to the UUID of the one you mean.`);
+}
+/** Scope label UUIDs, resolving any configured label *names* to their ids. */
+export async function resolveScopeLabelIds(ctx) {
+    const values = scopeLabelValues(ctx);
+    if (values.length === 0)
+        return [];
+    if (values.every((v) => UUID_RE.test(v)))
+        return values;
+    const apiKey = key(ctx);
+    const missing = (directory) => values.some((v) => !UUID_RE.test(v) && !directory.has(v.toLowerCase()));
+    let directory = await labelDirectory(apiKey);
+    // A label created after the directory was cached would otherwise stay
+    // unresolvable for the lifetime of the process: re-read once before
+    // declaring a name unknown.
+    if (missing(directory))
+        directory = await labelDirectory(apiKey, { refresh: true });
+    return values.map((value) => {
+        if (UUID_RE.test(value))
+            return value;
+        const matches = directory.get(value.toLowerCase()) ?? [];
+        if (matches.length === 0)
+            throw unknownLabelError(value);
+        if (matches.length > 1)
+            throw ambiguousLabelError(value, matches);
+        return matches[0].id;
+    });
+}
 export function isScoped(ctx) {
-    return scopeLabelIds(ctx).length > 0;
+    return scopeLabelValues(ctx).length > 0;
 }
-export function mergeIssueScopeFilter(ctx, filter) {
-    const ids = scopeLabelIds(ctx);
+export async function mergeIssueScopeFilter(ctx, filter) {
+    const ids = await resolveScopeLabelIds(ctx);
     if (ids.length === 0)
         return filter;
     const scopeFilter = { labels: { id: { in: ids } } };
@@ -45,8 +155,8 @@ export function mergeIssueScopeFilter(ctx, filter) {
         return scopeFilter;
     return { and: [filter, scopeFilter] };
 }
-export function issueHasScope(ctx, issue) {
-    const ids = new Set(scopeLabelIds(ctx));
+export async function issueHasScope(ctx, issue) {
+    const ids = new Set(await resolveScopeLabelIds(ctx));
     if (ids.size === 0)
         return true;
     const labels = issue?.labels?.nodes;
@@ -61,7 +171,7 @@ export async function assertIssueInScope(ctx, issueId) {
     if (!isScoped(ctx))
         return null;
     const issue = await getIssueForScope(ctx, issueId);
-    if (!issue || !issueHasScope(ctx, issue))
+    if (!issue || !(await issueHasScope(ctx, issue)))
         throw new Error("Linear issue is not available to this scoped connection");
     return issue;
 }
@@ -70,7 +180,7 @@ export async function assertCommentInScope(ctx, commentId) {
         return;
     const data = await gql(key(ctx), `query($id: String!) { comment(id: $id) { id issue { id identifier labels { nodes { id name } } } } }`, { id: commentId });
     const issue = data.comment?.issue;
-    if (!issue || !issueHasScope(ctx, issue))
+    if (!issue || !(await issueHasScope(ctx, issue)))
         throw new Error("Linear comment is not available to this scoped connection");
 }
 export async function assertAttachmentInScope(ctx, attachmentId) {
@@ -78,11 +188,11 @@ export async function assertAttachmentInScope(ctx, attachmentId) {
         return;
     const data = await gql(key(ctx), `query($id: String!) { attachment(id: $id) { id issue { id identifier labels { nodes { id name } } } } }`, { id: attachmentId });
     const issue = data.attachment?.issue;
-    if (!issue || !issueHasScope(ctx, issue))
+    if (!issue || !(await issueHasScope(ctx, issue)))
         throw new Error("Linear attachment is not available to this scoped connection");
 }
-export function forbidScopeLabelRemoval(ctx, labelIds) {
-    const scoped = new Set(scopeLabelIds(ctx));
+export async function forbidScopeLabelRemoval(ctx, labelIds) {
+    const scoped = new Set(await resolveScopeLabelIds(ctx));
     if (scoped.size === 0)
         return;
     const ids = Array.isArray(labelIds)
@@ -92,8 +202,8 @@ export function forbidScopeLabelRemoval(ctx, labelIds) {
         throw new Error("Cannot remove a required Linear scope label");
     }
 }
-export function ensureScopeLabelsOnCreateOrReplace(ctx, labelIds) {
-    const scoped = scopeLabelIds(ctx);
+export async function ensureScopeLabelsOnCreateOrReplace(ctx, labelIds) {
+    const scoped = await resolveScopeLabelIds(ctx);
     if (scoped.length === 0)
         return labelIds;
     const ids = new Set(Array.isArray(labelIds) ? labelIds.map(String) : []);
@@ -101,6 +211,16 @@ export function ensureScopeLabelsOnCreateOrReplace(ctx, labelIds) {
         ids.add(id);
     return [...ids];
 }
+/**
+ * Appended to the description of every action a scoped connection cannot
+ * use. Descriptions are static, but they are also all an agent sees when it
+ * picks an action (`actions.find`, the Vex catalog): without this, a scoped
+ * agent discovers the action, calls it, and only then learns it is blocked.
+ */
+export const SCOPED_UNAVAILABLE_NOTE = "Unavailable on scoped connections.";
+export function withScopedNote(description) {
+    return `${description} ${SCOPED_UNAVAILABLE_NOTE}`;
+}
 export function requireUnscoped(ctx, action) {
     if (isScoped(ctx)) {
         throw new Error(`${action} is not available to scoped Linear connections`);
@@ -195,13 +315,19 @@ export function bindListAction(rl) {
 export function bindGetAction(rl) {
     return (...args) => registerGetAction(rl, ...args);
 }
+/**
+ * Root fields a scoped connection may not read.
+ *
+ * The scope restricts *issue content*, so workspace metadata an agent needs
+ * to route and report on its own issues — cycles, users, teams, states and
+ * labels — stays readable. Fields that would leak other people's content or
+ * secrets are blocked, and a blocked field's description says so.
+ */
 const SCOPED_BLOCKED_ROOT_FIELDS = new Set([
     "attachments",
     "comments",
     "customView",
     "customViews",
-    "cycle",
-    "cycles",
     "initiative",
     "initiatives",
     "project",
@@ -209,8 +335,6 @@ const SCOPED_BLOCKED_ROOT_FIELDS = new Set([
     "projectMilestone",
     "projectMilestones",
     "projectUpdates",
-    "user",
-    "users",
     "webhook",
     "webhooks",
 ]);
@@ -221,7 +345,9 @@ function requireRootFieldAvailable(ctx, action, rootField) {
 export function registerListAction(rl, name, description, rootField, filterTypeName, selection) {
     rl.registerAction(name, {
         access: "read",
-        description,
+        description: SCOPED_BLOCKED_ROOT_FIELDS.has(rootField)
+            ? withScopedNote(description)
+            : description,
         inputSchema: t.Object(LIST_INPUT_SCHEMA),
         async execute(input, ctx) {
             requireRootFieldAvailable(ctx, name, rootField);
@@ -236,7 +362,9 @@ export function registerListAction(rl, name, description, rootField, filterTypeN
 export function registerGetAction(rl, name, description, rootField, selection) {
     rl.registerAction(name, {
         access: "read",
-        description,
+        description: SCOPED_BLOCKED_ROOT_FIELDS.has(rootField)
+            ? withScopedNote(description)
+            : description,
         inputSchema: t.Object({
             id: t.String({ description: "Identifier or slug" }),
         }),

package/dist/plugins/linear/src/states.js

@@ -1,5 +1,5 @@
 import * as t from "typebox";
-import { bindGetAction, bindListAction, gql, key, requireUnscoped, STATE_FIELDS, } from "./shared.js";
+import { bindGetAction, bindListAction, gql, key, requireUnscoped, STATE_FIELDS, withScopedNote, } from "./shared.js";
 export function registerStateActions(rl) {
     const listAction = bindListAction(rl);
     const getAction = bindGetAction(rl);
@@ -7,7 +7,7 @@ export function registerStateActions(rl) {
     getAction("state.get", "Get a workflow state by ID.", "workflowState", STATE_FIELDS);
     rl.registerAction("state.create", {
         access: "write",
-        description: "Create a workflow state in a team.",
+        description: withScopedNote("Create a workflow state in a team."),
         inputSchema: t.Object({
             teamId: t.String({ description: "The team associated with the state" }),
             name: t.String({ description: "The name of the state" }),
@@ -32,7 +32,7 @@ export function registerStateActions(rl) {
     });
     rl.registerAction("state.update", {
         access: "write",
-        description: "Update a workflow state. Type cannot be changed after creation.",
+        description: withScopedNote("Update a workflow state. Type cannot be changed after creation."),
         inputSchema: t.Object({
             id: t.String({ description: "The identifier of the state to update" }),
             name: t.Optional(t.String({ description: "The name of the state" })),

package/dist/plugins/linear/src/teams.js

@@ -1,5 +1,5 @@
 import * as t from "typebox";
-import { bindGetAction, bindListAction, gql, key, requireUnscoped, TEAM_FIELDS, USER_FIELDS, } from "./shared.js";
+import { bindGetAction, bindListAction, gql, key, requireUnscoped, TEAM_FIELDS, USER_FIELDS, withScopedNote, } from "./shared.js";
 export function registerTeamActions(rl) {
     const listAction = bindListAction(rl);
     const getAction = bindGetAction(rl);
@@ -7,7 +7,7 @@ export function registerTeamActions(rl) {
     getAction("team.get", "Get a team by ID or key.", "team", TEAM_FIELDS);
     rl.registerAction("team.create", {
         access: "write",
-        description: "Create a team. Most settings have sensible defaults.",
+        description: withScopedNote("Create a team. Most settings have sensible defaults."),
         inputSchema: t.Object({
             name: t.String({ description: "The name of the team" }),
             key: t.Optional(t.String({
@@ -51,7 +51,7 @@ export function registerTeamActions(rl) {
     });
     rl.registerAction("team.update", {
         access: "write",
-        description: "Update a team. Requires team owner or workspace admin permissions.",
+        description: withScopedNote("Update a team. Requires team owner or workspace admin permissions."),
         inputSchema: t.Object({
             id: t.String({ description: "The identifier of the team to update" }),
             name: t.Optional(t.String({ description: "The name of the team" })),
@@ -86,13 +86,14 @@ export function registerTeamActions(rl) {
     });
     rl.registerAction("team.members", {
         access: "read",
-        description: "List members of a team.",
+        description: "List members of a team. Same people surface as user.list, narrowed to one team.",
         inputSchema: t.Object({
             teamId: t.String({ description: "The identifier of the team" }),
             limit: t.Optional(t.Number({ description: "Max members to return (default 50)" })),
         }),
         async execute(input, ctx) {
-            requireUnscoped(ctx, "team.members");
+            // Team membership is workspace metadata, like user.list: readable
+            // under a scoped connection (SHFT-1644).
             const { teamId, limit } = input;
             const data = await gql(key(ctx), `query($id: String!, $first: Int) {
           team(id: $id) { members(first: $first) { nodes { ${USER_FIELDS} } } }

package/dist/plugins/linear/src/users.js

@@ -1,5 +1,5 @@
 import * as t from "typebox";
-import { bindGetAction, bindListAction, gql, key, requireUnscoped, USER_FIELDS, } from "./shared.js";
+import { bindGetAction, bindListAction, gql, key, requireUnscoped, USER_FIELDS, withScopedNote, } from "./shared.js";
 export function registerUserActions(rl) {
     const listAction = bindListAction(rl);
     const getAction = bindGetAction(rl);
@@ -7,7 +7,7 @@ export function registerUserActions(rl) {
     getAction("user.get", "Get a user by ID. Use 'me' to reference the authenticated user.", "user", USER_FIELDS);
     rl.registerAction("user.me", {
         access: "read",
-        description: "Get the authenticated user.",
+        description: "Get the authenticated user. Use this to resolve 'me' before filtering issues by assignee.",
         inputSchema: t.Object({}),
         async execute(_input, ctx) {
             const data = await gql(key(ctx), `query { viewer { ${USER_FIELDS} } }`);
@@ -16,7 +16,7 @@ export function registerUserActions(rl) {
     });
     rl.registerAction("user.update", {
         access: "write",
-        description: "Update a user. Use id='me' to update the authenticated user.",
+        description: withScopedNote("Update a user. Use id='me' to update the authenticated user."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the user to update. Use 'me' to reference the currently authenticated user",