@jam-mcp/server 1.2.0 → 1.3.0

package/README.md

@@ -70,10 +70,10 @@ auth login   Store Jira credentials in this user's OS secret store
 runtime      Show or change which JAM build this machine runs
 ```
 
-Written out, that is `npx --yes @jam-mcp/launcher@1.2.0 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.3.0 doctor`, or just `jam
 doctor` if you took the launcher's optional global install. Starting from
 nothing — no install, no runtime chosen yet — use
-`npx --yes @jam-mcp/bootstrap@1.2.0 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.3.0 init` instead.
 
 Credentials come from the process environment or this user's OS secret store —
 never from a repository file — and never appear in logs, telemetry, or tool

package/dist/adapters/jira-cloud/jira-assignee-resolution.adapter.d.ts

@@ -0,0 +1,39 @@
+import type { AssigneeCandidate } from "../../domain/write.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
+import type { JiraAssigneeResolutionPort } from "../../ports/jira-assignee-resolution.port.js";
+/**
+ * Jira Cloud REST v3 user directory, read-only.
+ *
+ * Two endpoints, two questions:
+ *
+ *  - `GET /rest/api/3/user/search?query=` - who might this name mean. Jira
+ *    matches display name and, where privacy settings allow it, email. The
+ *    answers are candidates.
+ *  - `GET /rest/api/3/user/assignable/search?issueKey=&accountId=` - may this
+ *    exact account hold this exact issue. Jira answers with the account when
+ *    it may and with nothing when it may not, which is the assignability check
+ *    without JAM having to interpret a permission model it does not own.
+ *
+ * `retry: false` on both. Their answers decide a mutation, so a
+ * retried-and-stale answer is worse than a failure.
+ *
+ * Email is deliberately not part of the identity JAM works with. Jira's
+ * privacy settings routinely blank it - most users on a real site come back
+ * with `emailAddress: ""` - so resolving on it would work for some people and
+ * silently fail for others on the same site.
+ */
+export declare class JiraCloudAssigneeResolutionAdapter implements JiraAssigneeResolutionPort {
+    private readonly client;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    searchUsers(query: string): Promise<AssigneeCandidate[]>;
+    /**
+     * `GET /rest/api/3/user?accountId=` - the exact lookup, not a search.
+     *
+     * Jira answers 404 when no such account exists or this token cannot see it.
+     * Both mean the same thing to a caller who wanted to assign it, so both
+     * become `undefined` rather than an error: "there is nobody to assign" is an
+     * answer, and the policy layer is where it turns into a refusal.
+     */
+    getUserByAccountId(accountId: string): Promise<AssigneeCandidate | undefined>;
+    isAssignable(issueKey: string, accountId: string): Promise<boolean>;
+}

package/dist/adapters/jira-cloud/jira-assignee-resolution.adapter.js

@@ -0,0 +1,94 @@
+import { JamError } from "../../domain/errors.js";
+import { JiraClient } from "./jira-client.js";
+/** How many candidates are worth reporting back to a human. */
+const SEARCH_LIMIT = 20;
+/**
+ * Jira Cloud REST v3 user directory, read-only.
+ *
+ * Two endpoints, two questions:
+ *
+ *  - `GET /rest/api/3/user/search?query=` - who might this name mean. Jira
+ *    matches display name and, where privacy settings allow it, email. The
+ *    answers are candidates.
+ *  - `GET /rest/api/3/user/assignable/search?issueKey=&accountId=` - may this
+ *    exact account hold this exact issue. Jira answers with the account when
+ *    it may and with nothing when it may not, which is the assignability check
+ *    without JAM having to interpret a permission model it does not own.
+ *
+ * `retry: false` on both. Their answers decide a mutation, so a
+ * retried-and-stale answer is worse than a failure.
+ *
+ * Email is deliberately not part of the identity JAM works with. Jira's
+ * privacy settings routinely blank it - most users on a real site come back
+ * with `emailAddress: ""` - so resolving on it would work for some people and
+ * silently fail for others on the same site.
+ */
+export class JiraCloudAssigneeResolutionAdapter {
+    client;
+    constructor(credentials, fetchImpl) {
+        this.client = fetchImpl ? new JiraClient(credentials, fetchImpl) : new JiraClient(credentials);
+    }
+    async searchUsers(query) {
+        const { data } = await this.client.request({
+            path: "rest/api/3/user/search",
+            query: { query, maxResults: SEARCH_LIMIT },
+            retry: false,
+        });
+        return toCandidates(data);
+    }
+    /**
+     * `GET /rest/api/3/user?accountId=` - the exact lookup, not a search.
+     *
+     * Jira answers 404 when no such account exists or this token cannot see it.
+     * Both mean the same thing to a caller who wanted to assign it, so both
+     * become `undefined` rather than an error: "there is nobody to assign" is an
+     * answer, and the policy layer is where it turns into a refusal.
+     */
+    async getUserByAccountId(accountId) {
+        try {
+            const { data } = await this.client.request({
+                path: "rest/api/3/user",
+                query: { accountId },
+                retry: false,
+            });
+            return toCandidates([data])[0];
+        }
+        catch (err) {
+            if (err instanceof JamError && err.code === "ISSUE_NOT_FOUND")
+                return undefined;
+            throw err;
+        }
+    }
+    async isAssignable(issueKey, accountId) {
+        const { data } = await this.client.request({
+            path: "rest/api/3/user/assignable/search",
+            query: { issueKey, accountId, maxResults: 1 },
+            retry: false,
+        });
+        // Jira answers with the account when it is assignable and with an empty
+        // list when it is not. Matching the id back is belt and braces: an answer
+        // about somebody else is not an answer to the question that was asked.
+        return toCandidates(data).some((u) => u.accountId === accountId);
+    }
+}
+/**
+ * Users JAM can work with, from whatever Jira sent.
+ *
+ * An entry with no accountId is dropped: accountId is the identity, and an
+ * entry without one cannot be assigned, verified, or told apart from another.
+ * App and customer accounts are dropped too - they are not people a human
+ * meant to name, and offering one as a candidate invites assigning an issue to
+ * an integration.
+ */
+function toCandidates(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((u) => typeof u?.accountId === "string" &&
+        (u.accountType === undefined || u.accountType === "atlassian"))
+        .map((u) => ({
+        accountId: u.accountId,
+        displayName: typeof u.displayName === "string" ? u.displayName : u.accountId,
+        active: u.active !== false,
+    }));
+}

package/dist/adapters/jira-cloud/jira-read.adapter.js

@@ -42,7 +42,16 @@ export class JiraCloudReadAdapter {
         });
         if (!data?.key)
             return { responseBytes: bytes };
-        return { issue: mapIssueWithMeta(data, this.config).issue, responseBytes: bytes };
+        // Read straight off the raw payload rather than through the mapper: the
+        // mapper's job is the shape the read tools see, and this identity is only
+        // for the write plane. Raw DTOs still stop here.
+        const assignee = data.fields?.assignee;
+        const accountId = typeof assignee?.accountId === "string" ? assignee.accountId : undefined;
+        return {
+            issue: mapIssueWithMeta(data, this.config).issue,
+            ...(accountId ? { assigneeAccountId: accountId } : {}),
+            responseBytes: bytes,
+        };
     }
     async getIssues(req) {
         const issues = [];

package/dist/adapters/jira-cloud/jira-write.adapter.d.ts

@@ -43,5 +43,14 @@ export declare class JiraCloudWriteAdapter implements JiraWritePort {
         id: string;
     }>;
     getTransitions(key: string): Promise<JiraTransition[]>;
+    /**
+     * `PUT /rest/api/3/issue/{key}/assignee` with an accountId.
+     *
+     * The dedicated assignment endpoint rather than a field update: assignment
+     * has its own permission and its own Jira semantics, and routing it through
+     * the generic field PUT would put it behind the field whitelist, where it
+     * does not belong.
+     */
+    assignIssue(key: string, accountId: string): Promise<void>;
     transitionIssue(key: string, transitionId: string): Promise<void>;
 }

package/dist/adapters/jira-cloud/jira-write.adapter.js

@@ -91,6 +91,22 @@ export class JiraCloudWriteAdapter {
             to: t.to?.name ?? t.name ?? "",
         }));
     }
+    /**
+     * `PUT /rest/api/3/issue/{key}/assignee` with an accountId.
+     *
+     * The dedicated assignment endpoint rather than a field update: assignment
+     * has its own permission and its own Jira semantics, and routing it through
+     * the generic field PUT would put it behind the field whitelist, where it
+     * does not belong.
+     */
+    async assignIssue(key, accountId) {
+        await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}/assignee`,
+            method: "PUT",
+            body: { accountId },
+            retry: false,
+        });
+    }
     async transitionIssue(key, transitionId) {
         await this.client.request({
             path: `rest/api/3/issue/${encodeURIComponent(key)}/transitions`,

package/dist/application/apply-create-issue.js

@@ -127,7 +127,7 @@ async function verify(deps, plan, issueKey) {
     if (createdProject !== plan.projectKey) {
         throw verificationFailed(plan, issueKey, { project: plan.projectKey }, { project: createdProject ?? issueKey });
     }
-    const issue = await readIssue(deps, issueKey);
+    const { issue } = await readIssue(deps, issueKey);
     const observed = {};
     for (const field of Object.keys(plan.intendedAfter)) {
         observed[field] = observedValue(issue, field);

package/dist/application/apply-write.js

@@ -1,5 +1,6 @@
 import { JamError, toJamError } from "../domain/errors.js";
 import { readModeAfterWrite } from "../policy/consistency-policy.js";
+import { assertAssignable } from "../policy/assignee-policy.js";
 import { assertUnchanged } from "../policy/write-policy.js";
 import { applyCreateIssue } from "./apply-create-issue.js";
 import { readIssue } from "./plan-write.js";
@@ -35,7 +36,12 @@ export async function applyWritePlan(deps, request) {
     if (plan.kind === "create-issue")
         return applyCreateIssue(deps, plan);
     const current = await readIssue(deps, plan.issueKey);
-    assertUnchanged(plan.issueKey, plan.baseUpdated, current.updated);
+    assertUnchanged(plan.issueKey, plan.baseUpdated, current.issue.updated);
+    // Whatever the plan depends on that the revision check cannot see, checked
+    // again here. For an assignment that is the target's permission to hold this
+    // issue: it can be revoked between planning and applying, and a plan that
+    // was valid is not the same as a plan that is still valid.
+    await revalidate(deps, plan);
     const outcome = await mutate(deps, plan);
     const after = await verify(deps, plan);
     deps.writePlans.consume(plan.planId);
@@ -49,6 +55,18 @@ export async function applyWritePlan(deps, request) {
         ...(outcome.commentId ? { commentId: outcome.commentId } : {}),
     };
 }
+/**
+ * Re-derive the premises the revision check does not cover.
+ *
+ * Only `assignee.update` has any: the rest are fully described by the issue's
+ * own state, which `assertUnchanged` already compared.
+ */
+async function revalidate(deps, plan) {
+    if (plan.mutation.kind !== "assignee")
+        return;
+    const target = plan.intendedAfter["assignee"];
+    assertAssignable(plan.issueKey, target, await deps.jiraAssignees.isAssignable(plan.issueKey, plan.mutation.accountId));
+}
 /**
  * Send the mutation, once.
  *
@@ -71,6 +89,9 @@ async function mutate(deps, plan) {
             case "transition":
                 await deps.jiraWrite.transitionIssue(plan.issueKey, plan.mutation.transitionId);
                 return {};
+            case "assignee":
+                await deps.jiraWrite.assignIssue(plan.issueKey, plan.mutation.accountId);
+                return {};
             case "create":
                 // Unreachable: a create plan is routed to applyCreateIssue above. The
                 // case exists so adding a mutation kind is a compile error here rather
@@ -103,7 +124,22 @@ function isAmbiguous(err) {
  * ours.
  */
 async function verify(deps, plan) {
-    const issue = await readIssue(deps, plan.issueKey);
+    const snapshot = await readIssue(deps, plan.issueKey);
+    const issue = snapshot.issue;
+    if (plan.mutation.kind === "assignee") {
+        // On the accountId, never on the display name. Two people can share a
+        // name, so a name comparison would accept the wrong person's assignment as
+        // proof of the right one's - which is the entire reason resolution went to
+        // the trouble of producing an identity.
+        const expected = plan.intendedAfter["assignee"];
+        const observed = snapshot.assigneeAccountId
+            ? { accountId: snapshot.assigneeAccountId, displayName: issue.assignee ?? "" }
+            : null;
+        if (snapshot.assigneeAccountId !== expected.accountId) {
+            throw verificationFailed(plan, { assignee: expected }, { assignee: observed });
+        }
+        return { assignee: { accountId: expected.accountId, displayName: issue.assignee ?? expected.displayName } };
+    }
     if (plan.mutation.kind === "comment") {
         // Direct issue GET again, not the bulk endpoint: this is post-write
         // confirmation, and ConsistencyPolicy makes no exception for the read that

package/dist/application/plan-write.d.ts

@@ -36,4 +36,9 @@ export declare function planWrite(deps: JamDeps, request: PlanWriteRequest): Pro
  * The one read every write goes through - the pre-write conflict check, the
  * post-write confirmation, and the post-create confirmation.
  */
-export declare function readIssue(deps: JamDeps, issueKey: string): Promise<FullIssueContext>;
+export type IssueSnapshot = {
+    issue: FullIssueContext;
+    /** Identity of the current assignee, which `issue.assignee` cannot supply. */
+    assigneeAccountId?: string;
+};
+export declare function readIssue(deps: JamDeps, issueKey: string): Promise<IssueSnapshot>;

package/dist/application/plan-write.js

@@ -1,5 +1,6 @@
 import { JamError } from "../domain/errors.js";
 import { assertExistingIssueOperation, assertFieldsAllowed, assertOperationAllowed, assertWriteScope, PLAN_TTL_MS, resolveTransition, } from "../policy/write-policy.js";
+import { assertAssignable, assertNotAlreadyAssigned, exactMatches, resolveAssignee, } from "../policy/assignee-policy.js";
 import { planCreateIssue } from "./plan-create-issue.js";
 /**
  * Work out whether a requested change is currently possible, and describe it.
@@ -30,8 +31,9 @@ export async function planWrite(deps, request) {
     // does not write should get that answer, not a round trip and then that
     // answer.
     const input = validateInput(operation, request.input);
-    const issue = await readIssue(deps, issueKey);
-    const { before, intendedAfter, mutation, transition } = await describe(deps, operation, issueKey, issue, input);
+    const snapshot = await readIssue(deps, issueKey);
+    const issue = snapshot.issue;
+    const { before, intendedAfter, mutation, transition, baseAssigneeAccountId } = await describe(deps, operation, issueKey, snapshot, input);
     const createdAt = new Date();
     const plan = deps.writePlans.create({
         kind: "existing-issue",
@@ -44,6 +46,7 @@ export async function planWrite(deps, request) {
         createdAt: createdAt.toISOString(),
         expiresAt: new Date(createdAt.getTime() + PLAN_TTL_MS).toISOString(),
         ...(transition ? { transition } : {}),
+        ...(baseAssigneeAccountId ? { baseAssigneeAccountId } : {}),
         mutation,
     });
     return {
@@ -60,20 +63,8 @@ export async function planWrite(deps, request) {
         },
     };
 }
-/**
- * The issue as Jira has it, read directly by key.
- *
- * `getIssue`, not `getIssues`: ConsistencyPolicy requires a direct issue GET
- * for anything that decides or confirms a write, and the bulk endpoint is not
- * one. A JQL result can lag behind the issue it describes; a bulk fetch is
- * free to answer from a different path than the single-issue endpoint. Neither
- * difference matters for ordinary reads, and both matter here.
- *
- * The one read every write goes through - the pre-write conflict check, the
- * post-write confirmation, and the post-create confirmation.
- */
 export async function readIssue(deps, issueKey) {
-    const { issue: found } = await deps.jira.getIssue({
+    const { issue: found, assigneeAccountId } = await deps.jira.getIssue({
         key: issueKey,
         // `issuetype` and `description` are here for creation's verification step,
         // which has to confirm the issue Jira made is the one that was asked for.
@@ -85,6 +76,7 @@ export async function readIssue(deps, issueKey) {
             "status",
             "issuetype",
             "description",
+            "assignee",
             "priority",
             "labels",
             "components",
@@ -94,7 +86,7 @@ export async function readIssue(deps, issueKey) {
     if (!found) {
         throw new JamError("ISSUE_NOT_FOUND", `Jira has no issue ${issueKey}, or it is not visible to this account.`, { issueKey });
     }
-    return found;
+    return { issue: found, ...(assigneeAccountId ? { assigneeAccountId } : {}) };
 }
 /**
  * The issue an existing-issue operation names, or a refusal that says why.
@@ -136,9 +128,17 @@ function validateInput(operation, raw) {
             }
             return { status: status.trim() };
         }
+        case "assignee.update": {
+            const assignee = raw.assignee;
+            if (typeof assignee !== "string" || assignee.trim().length === 0) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "assignee.update needs non-empty `input.assignee` - a display name, or an accountId.", { operation });
+            }
+            return { assignee: assignee.trim() };
+        }
     }
 }
-async function describe(deps, operation, issueKey, issue, input) {
+async function describe(deps, operation, issueKey, snapshot, input) {
+    const issue = snapshot.issue;
     switch (operation) {
         case "comment.add": {
             const { text } = input;
@@ -178,8 +178,54 @@ async function describe(deps, operation, issueKey, issue, input) {
                 transition,
             };
         }
+        case "assignee.update": {
+            const { assignee: requested } = input;
+            // Ask Jira who this is, and decide from what it says. The requested
+            // string never reaches a mutation: what gets written is the accountId
+            // that resolution settled on, and resolution refuses rather than picks
+            // when the answer is not one person.
+            const target = resolveAssignee(requested, await findCandidates(deps, requested));
+            // Two independent refusals, in the order that costs least. Already-set
+            // needs no Jira call; assignability does.
+            assertNotAlreadyAssigned(issueKey, snapshot.assigneeAccountId, target);
+            assertAssignable(issueKey, target, await deps.jiraAssignees.isAssignable(issueKey, target.accountId));
+            return {
+                before: {
+                    assignee: snapshot.assigneeAccountId
+                        ? { accountId: snapshot.assigneeAccountId, displayName: issue.assignee ?? "" }
+                        : null,
+                },
+                intendedAfter: { assignee: target },
+                mutation: { kind: "assignee", accountId: target.accountId },
+                ...(snapshot.assigneeAccountId
+                    ? { baseAssigneeAccountId: snapshot.assigneeAccountId }
+                    : {}),
+            };
+        }
     }
 }
+/**
+ * Who Jira thinks this string could be.
+ *
+ * The search first, because it answers both halves of the contract most of the
+ * time - Jira's user search currently matches an accountId as readily as a
+ * name. "Currently" is the problem: that is a property of a substring search
+ * rather than a promise, and the contract says an accountId identifies a
+ * person. So when the search settles nothing, the exact lookup is asked before
+ * giving up.
+ *
+ * Ordered this way because it costs nothing on the paths that work. The extra
+ * request happens only where resolution was about to fail anyway, and the
+ * string is never inspected to guess whether it looks like an accountId - Jira
+ * is asked, and Jira answers.
+ */
+async function findCandidates(deps, requested) {
+    const candidates = await deps.jiraAssignees.searchUsers(requested);
+    if (exactMatches(requested, candidates).length > 0)
+        return candidates;
+    const byId = await deps.jiraAssignees.getUserByAccountId(requested);
+    return byId ? [byId] : candidates;
+}
 function currentValue(issue, field) {
     switch (field) {
         case "summary":

package/dist/bootstrap/mcp-config-merger.d.ts

@@ -13,7 +13,7 @@ import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.2.0", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.3.0", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded path to one

package/dist/deps.d.ts

@@ -4,6 +4,7 @@ import type { ProjectConfig } from "./config/schema.js";
 import type { CachePort } from "./ports/cache.port.js";
 import type { CredentialPort } from "./ports/credentials.port.js";
 import type { JiraReadPort } from "./ports/jira-read.port.js";
+import type { JiraAssigneeResolutionPort } from "./ports/jira-assignee-resolution.port.js";
 import type { JiraCreateMetadataPort } from "./ports/jira-create-metadata.port.js";
 import type { JiraWritePort } from "./ports/jira-write.port.js";
 import { WritePlanStore } from "./application/write-plan-store.js";
@@ -29,6 +30,12 @@ export type JamDeps = {
      * completeness semantics would mean nothing for it.
      */
     jiraCreateMetadata: JiraCreateMetadataPort;
+    /**
+     * Who a name refers to, and who may hold an issue. A fourth port for the
+     * same reason as the third: it reads a directory rather than an issue, and
+     * it mutates nothing.
+     */
+    jiraAssignees: JiraAssigneeResolutionPort;
     /**
      * Plans awaiting apply. Lives for the life of this server process - see
      * WritePlanStore for why it is not persisted.
@@ -46,6 +53,8 @@ export type BuildDepsOptions = {
     jiraWrite?: JiraWritePort;
     /** Injected by tests so create metadata comes from a fixture, not a site. */
     jiraCreateMetadata?: JiraCreateMetadataPort;
+    /** Injected by tests so user resolution never reaches a real directory. */
+    jiraAssignees?: JiraAssigneeResolutionPort;
     /** Injected by tests to bypass the real process/registry credential lookup. */
     credentials?: CredentialPort;
     /**

package/dist/deps.js

@@ -38,6 +38,11 @@ export async function buildDeps(options = {}) {
         const { JiraCloudCreateMetadataAdapter } = await import("./adapters/jira-cloud/jira-create-metadata.adapter.js");
         jiraCreateMetadata = new JiraCloudCreateMetadataAdapter(credentials);
     }
+    let jiraAssignees = options.jiraAssignees;
+    if (!jiraAssignees) {
+        const { JiraCloudAssigneeResolutionAdapter } = await import("./adapters/jira-cloud/jira-assignee-resolution.adapter.js");
+        jiraAssignees = new JiraCloudAssigneeResolutionAdapter(credentials);
+    }
     return {
         config: resolved.config,
         configPath: resolved.configPath,
@@ -45,6 +50,7 @@ export async function buildDeps(options = {}) {
         jira,
         jiraWrite,
         jiraCreateMetadata,
+        jiraAssignees,
         writePlans: new WritePlanStore(),
         cache: new NoopCache(),
         telemetry,

package/dist/domain/errors.d.ts

@@ -5,7 +5,7 @@
  * is mapped onto one of these codes so the agent (and `jam doctor`) can reason
  * about failures without parsing vendor-specific payloads.
  */
-export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", "JAM_WRITE_VALUE_NOT_ALLOWED", "JAM_WRITE_SCHEMA_CHANGED", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
+export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", "JAM_WRITE_VALUE_NOT_ALLOWED", "JAM_WRITE_SCHEMA_CHANGED", "JAM_WRITE_ASSIGNEE_NOT_FOUND", "JAM_WRITE_ASSIGNEE_AMBIGUOUS", "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", "JAM_WRITE_ASSIGNEE_ALREADY_SET", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
 export type JamErrorCode = (typeof JAM_ERROR_CODES)[number];
 export type JamErrorPayload = {
     error: {

package/dist/domain/errors.js

@@ -34,6 +34,14 @@ export const JAM_ERROR_CODES = [
     "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED",
     "JAM_WRITE_VALUE_NOT_ALLOWED",
     "JAM_WRITE_SCHEMA_CHANGED",
+    // Assignment. A name is not an identity, and Jira decides who may hold an
+    // issue - so "nobody by that name", "several people by that name", "that
+    // person may not hold this issue" and "they already do" are four different
+    // things for a caller to do next, and none of them is "try again".
+    "JAM_WRITE_ASSIGNEE_NOT_FOUND",
+    "JAM_WRITE_ASSIGNEE_AMBIGUOUS",
+    "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE",
+    "JAM_WRITE_ASSIGNEE_ALREADY_SET",
     "JAM_WRITE_PLAN_NOT_FOUND",
     "JAM_WRITE_PLAN_EXPIRED",
     "JAM_WRITE_CONFLICT",

package/dist/domain/write.d.ts

@@ -20,9 +20,9 @@
  * layer: these name an issue, creation names a project; these compare a
  * revision to detect a conflict, creation has no revision to compare.
  */
-export declare const EXISTING_ISSUE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition"];
+export declare const EXISTING_ISSUE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "assignee.update"];
 /** The operations the public MCP surface accepts. Nothing else is reachable. */
-export declare const WRITE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "issue.create"];
+export declare const WRITE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "assignee.update", "issue.create"];
 export type ExistingIssueOperation = (typeof EXISTING_ISSUE_OPERATIONS)[number];
 export type WriteOperation = (typeof WRITE_OPERATIONS)[number];
 /**
@@ -48,6 +48,32 @@ export type FieldUpdateInput = {
 export type StatusTransitionInput = {
     status: string;
 };
+/**
+ * Who to assign an issue to, as a person would say it.
+ *
+ * A display name, or an accountId if the caller already has one. Either way it
+ * is a selector, not an identifier: nothing here is ever sent to Jira. It is
+ * resolved against Jira's own user directory first, and what gets written is
+ * the accountId that resolution produced.
+ */
+export type AssigneeUpdateInput = {
+    assignee: string;
+};
+/**
+ * A Jira user as JAM identifies them.
+ *
+ * `accountId` is the identity; `displayName` is for the human reading the
+ * receipt. They are not interchangeable - two people can share a display name,
+ * which is precisely why an assignment is verified on the accountId.
+ */
+export type AssigneeRef = {
+    accountId: string;
+    displayName: string;
+};
+/** A user Jira offered in answer to a search. */
+export type AssigneeCandidate = AssigneeRef & {
+    active: boolean;
+};
 /**
  * Fields `issue.create` may set.
  *
@@ -67,7 +93,7 @@ export type CreateIssueInput = {
     labels?: string[];
     components?: string[];
 };
-export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput | CreateIssueInput;
+export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput | AssigneeUpdateInput | CreateIssueInput;
 /** An issue type as Jira offers it for one project, right now. */
 export type CreateIssueType = {
     id: string;
@@ -154,6 +180,14 @@ export type ExistingIssueWritePlan = WritePlanCommon & {
      * from a status name.
      */
     transition?: JiraTransition;
+    /**
+     * Who the issue was assigned to when the plan was made, by identity.
+     *
+     * Present only for `assignee.update`, and separate from `before` because
+     * `before` is what a receipt shows a human while this is what apply compares.
+     * `undefined` means the issue was unassigned.
+     */
+    baseAssigneeAccountId?: string;
 };
 /**
  * A plan to create an issue that does not exist yet.
@@ -185,6 +219,9 @@ export type WriteMutation = {
 } | {
     kind: "transition";
     transitionId: string;
+} | {
+    kind: "assignee";
+    accountId: string;
 } | {
     kind: "create";
     fields: Record<string, unknown>;

package/dist/domain/write.js

@@ -24,6 +24,7 @@ export const EXISTING_ISSUE_OPERATIONS = [
     "comment.add",
     "field.update",
     "status.transition",
+    "assignee.update",
 ];
 /** The operations the public MCP surface accepts. Nothing else is reachable. */
 export const WRITE_OPERATIONS = [...EXISTING_ISSUE_OPERATIONS, "issue.create"];

package/dist/mcp/tools/jira-write-plan.tool.js

@@ -10,12 +10,15 @@ Operations on an issue that already exists - these need \`key\`:
 - comment.add        input: { "text": "..." }        plain text; JAM converts it, do not send ADF
 - field.update       input: { "summary"?, "priority"?, "labels"?, "components"? }
 - status.transition  input: { "status": "Done" }     JAM asks Jira which transitions exist and matches yours
+- assignee.update    input: { "assignee": "..." }     a display name or an accountId; JAM resolves it against Jira's own directory
 
 Creating an issue - no \`key\`, because there is no issue yet:
 - issue.create       input: { "issueType": "Task", "summary": "...", "description"?, "priority"?, "labels"?, "components"? }
 
 issue.create goes into the project this workspace is bound to; the project is not a parameter. Planning reads Jira's create schema for that project first, so an issue type Jira does not offer, a priority or component outside its allowed values, and a project whose create screen requires a field JAM cannot set are all refused here rather than attempted. \`description\` is plain text, like a comment. Not settable in this version: assignee, reporter, parent, custom fields, attachments.
 
+assignee.update never sends the name you pass. JAM searches Jira's user directory, and assigns only when exactly one user matches your string exactly - an exact display name (case-insensitive) or an accountId. A partial match is Jira reporting a similarity, not identifying a person, so several matches or none come back as a refusal with the candidates attached: name one exactly, or pass their accountId. JAM also checks Jira offers that person as an assignee for this issue, before planning and again before writing, and confirms the result by accountId rather than by name. Unassigning, and setting an assignee while creating, are not in this version.
+
 Writes are limited to the Jira project this workspace is bound to; a key from another project is refused rather than attempted.
 
 The plan records what the issue looked like when it was made, and expires. If the issue changes in the meantime, jira_write_apply refuses with JAM_WRITE_CONFLICT - re-plan against the new state rather than forcing the old one through.
@@ -34,7 +37,7 @@ export function registerJiraWritePlan(server, deps) {
                 .string()
                 .min(1)
                 .optional()
-                .describe('Issue key, e.g. "PROJECT-123". Required for comment.add, field.update and status.transition; omit for issue.create, which has no issue yet. Must be in the configured project.'),
+                .describe('Issue key, e.g. "PROJECT-123". Required for every operation that changes an existing issue; omit for issue.create, which has no issue yet. Must be in the configured project.'),
             operation: z
                 .enum(WRITE_OPERATIONS)
                 .describe(`What to do: ${WRITE_OPERATIONS.join(", ")}.`),
@@ -52,6 +55,11 @@ export function registerJiraWritePlan(server, deps) {
                     .min(1)
                     .optional()
                     .describe("status.transition: the status to move to, e.g. \"Done\"."),
+                assignee: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe("assignee.update: who to assign, as an exact display name or an accountId. Not settable through field.update."),
                 issueType: z
                     .string()
                     .min(1)
@@ -69,7 +77,7 @@ export function registerJiraWritePlan(server, deps) {
                     .optional()
                     .describe("Component names. Replaces the whole component set."),
             })
-                .describe(`Operation input. field.update accepts only ${WRITABLE_FIELDS.join(", ")}; issue.create accepts only ${CREATABLE_FIELDS.join(", ")}. Custom fields and assignee are not writable by either.`),
+                .describe(`Operation input. field.update accepts only ${WRITABLE_FIELDS.join(", ")}; issue.create accepts only ${CREATABLE_FIELDS.join(", ")}. Custom fields are not writable by either, and the assignee is changed through assignee.update rather than through field.update.`),
         },
         // Planning reads Jira and decides; it never mutates. Hosts are free to
         // run it without asking, which is what keeps the two-step shape cheap.

package/dist/policy/assignee-policy.d.ts

@@ -0,0 +1,60 @@
+import type { AssigneeCandidate, AssigneeRef } from "../domain/write.js";
+/**
+ * Turning a name into a person, without ever guessing which person.
+ *
+ * Jira's user search is a substring search: "min" finds Min Kim and Minho
+ * Park, and it returns them in whatever order it likes. An agent handing JAM a
+ * name is describing an intent, not identifying an account - so the search is
+ * how candidates are found, and never how one of them is chosen.
+ *
+ * The rule is that JAM assigns only when the answer is unambiguous on its own
+ * terms: one exact identity. Everything else comes back as a refusal carrying
+ * the candidates, so the next move is to name one of them precisely rather
+ * than to hope the same query resolves differently.
+ *
+ * This costs an agent a round trip on ambiguity. The alternative costs someone
+ * an issue assigned to the wrong colleague, discovered later.
+ */
+/**
+ * Which candidate the caller meant, if exactly one is certain.
+ *
+ * In order:
+ *
+ *  1. An exact accountId. The caller already had an identity; nothing to guess.
+ *  2. Exactly one candidate whose display name matches exactly, ignoring case
+ *     and surrounding space. "task" and "Task" are the same intent, and an
+ *     agent cannot learn a directory's casing before asking.
+ *
+ * Nothing else resolves. A single substring hit is still a substring hit: it
+ * is Jira saying "this contains what you typed", not "this is who you meant".
+ */
+export declare function resolveAssignee(requested: string, candidates: AssigneeCandidate[]): AssigneeRef;
+/**
+ * Refuse an assignment Jira would not permit, before asking it to.
+ *
+ * Assignability is a permission question with a per-project answer, and JAM
+ * does not model Jira's permission scheme - it asks. Called at plan time so a
+ * refusal is a JAM decision rather than a 400, and again immediately before
+ * the write, because a permission that held when the plan was made is not the
+ * same as one that still holds.
+ */
+export declare function assertAssignable(issueKey: string, target: AssigneeRef, assignable: boolean): void;
+/**
+ * Refuse an assignment that would change nothing.
+ *
+ * Not an error in Jira's eyes, and not harmful - but a write JAM reports as
+ * applied should be a write that happened. Saying so plainly is more useful
+ * than a receipt claiming to have changed something that already was.
+ */
+export declare function assertNotAlreadyAssigned(issueKey: string, current: string | undefined, target: AssigneeRef): void;
+/**
+ * The candidates this string identifies exactly, if any.
+ *
+ * Exported so the caller can tell "the search settled it" from "the search did
+ * not" without reimplementing the rule - a second copy of what counts as exact
+ * is a second answer waiting to disagree with this one.
+ *
+ * An accountId match wins outright: it is an identity, and a display name that
+ * happens to equal somebody's account id is not a reason to consider them.
+ */
+export declare function exactMatches(requested: string, candidates: AssigneeCandidate[]): AssigneeCandidate[];

package/dist/policy/assignee-policy.js

@@ -0,0 +1,103 @@
+import { JamError } from "../domain/errors.js";
+/**
+ * Turning a name into a person, without ever guessing which person.
+ *
+ * Jira's user search is a substring search: "min" finds Min Kim and Minho
+ * Park, and it returns them in whatever order it likes. An agent handing JAM a
+ * name is describing an intent, not identifying an account - so the search is
+ * how candidates are found, and never how one of them is chosen.
+ *
+ * The rule is that JAM assigns only when the answer is unambiguous on its own
+ * terms: one exact identity. Everything else comes back as a refusal carrying
+ * the candidates, so the next move is to name one of them precisely rather
+ * than to hope the same query resolves differently.
+ *
+ * This costs an agent a round trip on ambiguity. The alternative costs someone
+ * an issue assigned to the wrong colleague, discovered later.
+ */
+/**
+ * Which candidate the caller meant, if exactly one is certain.
+ *
+ * In order:
+ *
+ *  1. An exact accountId. The caller already had an identity; nothing to guess.
+ *  2. Exactly one candidate whose display name matches exactly, ignoring case
+ *     and surrounding space. "task" and "Task" are the same intent, and an
+ *     agent cannot learn a directory's casing before asking.
+ *
+ * Nothing else resolves. A single substring hit is still a substring hit: it
+ * is Jira saying "this contains what you typed", not "this is who you meant".
+ */
+export function resolveAssignee(requested, candidates) {
+    const wanted = requested.trim();
+    if (wanted.length === 0) {
+        throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "assignee.update needs a non-empty `input.assignee`.", { operation: "assignee.update" });
+    }
+    const exact = exactMatches(wanted, candidates);
+    if (exact.length === 0) {
+        throw new JamError("JAM_WRITE_ASSIGNEE_NOT_FOUND", candidates.length === 0
+            ? `Jira has no user matching "${requested}".`
+            : `No Jira user is exactly "${requested}". JAM assigns only on an exact display name or an accountId, because a partial match is Jira reporting a similarity rather than identifying a person. Name one of the candidates exactly, or pass their accountId.`, { requested, candidates: describe(candidates) });
+    }
+    if (exact.length > 1) {
+        // Two people really can share a display name. Picking either would be a
+        // coin toss whose result is somebody's issue.
+        throw new JamError("JAM_WRITE_ASSIGNEE_AMBIGUOUS", `"${requested}" matches ${exact.length} Jira users exactly. Pass the accountId of the one you mean.`, { requested, candidates: describe(exact) });
+    }
+    const match = exact[0];
+    if (!match.active) {
+        throw new JamError("JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", `${match.displayName} is a deactivated Jira account, so this issue cannot be assigned to them.`, { requested, accountId: match.accountId, reason: "INACTIVE" });
+    }
+    return { accountId: match.accountId, displayName: match.displayName };
+}
+/**
+ * Refuse an assignment Jira would not permit, before asking it to.
+ *
+ * Assignability is a permission question with a per-project answer, and JAM
+ * does not model Jira's permission scheme - it asks. Called at plan time so a
+ * refusal is a JAM decision rather than a 400, and again immediately before
+ * the write, because a permission that held when the plan was made is not the
+ * same as one that still holds.
+ */
+export function assertAssignable(issueKey, target, assignable) {
+    if (assignable)
+        return;
+    throw new JamError("JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", `Jira does not offer ${target.displayName} as an assignee for ${issueKey}. They may lack the assignable-user permission in this project, or have lost it since this plan was made.`, { issueKey, accountId: target.accountId, displayName: target.displayName });
+}
+/**
+ * Refuse an assignment that would change nothing.
+ *
+ * Not an error in Jira's eyes, and not harmful - but a write JAM reports as
+ * applied should be a write that happened. Saying so plainly is more useful
+ * than a receipt claiming to have changed something that already was.
+ */
+export function assertNotAlreadyAssigned(issueKey, current, target) {
+    if (current !== target.accountId)
+        return;
+    throw new JamError("JAM_WRITE_ASSIGNEE_ALREADY_SET", `${issueKey} is already assigned to ${target.displayName}. Nothing to change.`, { issueKey, accountId: target.accountId, displayName: target.displayName });
+}
+/**
+ * The candidates this string identifies exactly, if any.
+ *
+ * Exported so the caller can tell "the search settled it" from "the search did
+ * not" without reimplementing the rule - a second copy of what counts as exact
+ * is a second answer waiting to disagree with this one.
+ *
+ * An accountId match wins outright: it is an identity, and a display name that
+ * happens to equal somebody's account id is not a reason to consider them.
+ */
+export function exactMatches(requested, candidates) {
+    const wanted = requested.trim();
+    const byAccountId = candidates.filter((c) => c.accountId === wanted);
+    if (byAccountId.length > 0)
+        return byAccountId;
+    return candidates.filter((c) => c.displayName.trim().toLowerCase() === wanted.toLowerCase());
+}
+/** Candidates as an agent can act on them: a name to repeat, and an id to be sure. */
+function describe(candidates) {
+    return candidates.map((c) => ({
+        accountId: c.accountId,
+        displayName: c.displayName,
+        active: c.active,
+    }));
+}

package/dist/ports/jira-assignee-resolution.port.d.ts

@@ -0,0 +1,51 @@
+import type { AssigneeCandidate } from "../domain/write.js";
+/**
+ * Who Jira thinks a name refers to, and whether they can hold this issue.
+ *
+ * A third read-shaped port, for the same reason `JiraCreateMetadataPort` is
+ * one: nothing here mutates, so it does not belong behind the write port's
+ * no-retry contract, and it answers a question about a directory rather than
+ * about an issue, so the read port's completeness semantics would mean nothing
+ * for it.
+ *
+ * The two calls are deliberately separate questions. Searching answers "who
+ * did the caller mean", and it is allowed to be fuzzy - Jira matches on
+ * substrings, and a partial match is a suggestion to show a human. Checking
+ * assignability answers "may this exact person hold this exact issue", and it
+ * is not fuzzy at all: it takes an accountId that resolution has already
+ * settled on. Collapsing them would let a substring match decide a mutation.
+ *
+ * Neither call retries. Their answers decide a mutation, and a retried answer
+ * is a possibly-stale one - the same argument that keeps `getTransitions` and
+ * the create metadata calls on the non-retrying side.
+ */
+export interface JiraAssigneeResolutionPort {
+    /**
+     * Users matching a query, as Jira's own directory reports them.
+     *
+     * Fuzzy by nature. What comes back is candidates, never a decision - see
+     * `resolveAssignee` for what JAM will and will not do with them.
+     */
+    searchUsers(query: string): Promise<AssigneeCandidate[]>;
+    /**
+     * One user, looked up by identity rather than found by searching.
+     *
+     * JAM's contract says `assignee` may be an accountId, and a contract about
+     * identity has to be met by an identity lookup. Jira's user search does
+     * currently return a user when the query happens to be their accountId, but
+     * that is a property of a substring search, not a promise - relying on it
+     * means the accountId half of the contract holds by coincidence.
+     *
+     * Absent means Jira has no such account, or this token cannot see it. Both
+     * are "you cannot assign this", which is the caller's answer either way.
+     */
+    getUserByAccountId(accountId: string): Promise<AssigneeCandidate | undefined>;
+    /**
+     * Whether this exact account may be assigned this exact issue, right now.
+     *
+     * Asked by accountId, so it is an identity question rather than a name one.
+     * Asked again immediately before the write, because a permission that held
+     * when the plan was made is not the same as one that still holds.
+     */
+    isAssignable(issueKey: string, accountId: string): Promise<boolean>;
+}

package/dist/ports/jira-assignee-resolution.port.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/jira-read.port.d.ts

@@ -27,6 +27,17 @@ export type GetIssueRequest = {
 export type GetIssueResult = {
     /** Absent when Jira has no such issue, or this account cannot see it. */
     issue?: FullIssueContext;
+    /**
+     * Who the issue is assigned to, by identity rather than by name.
+     *
+     * Here rather than on the issue because only the write plane needs it. Two
+     * people can share a display name, so `assignee` cannot settle whether an
+     * assignment landed on the right person - and the read tools have no use for
+     * an accountId, so their payload does not grow one.
+     *
+     * Absent when the issue is unassigned, or when the field was not requested.
+     */
+    assigneeAccountId?: string;
     responseBytes: number;
 };
 export type GetIssuesResult = {

package/dist/ports/jira-write.port.d.ts

@@ -32,4 +32,12 @@ export interface JiraWritePort {
     /** Transitions Jira offers for this issue right now, for this account. */
     getTransitions(key: string): Promise<JiraTransition[]>;
     transitionIssue(key: string, transitionId: string): Promise<void>;
+    /**
+     * Assign an issue to one account.
+     *
+     * By accountId, never by name: Jira Cloud identifies users by account, and a
+     * display name is a label two people can share. Which account it is was
+     * settled during planning.
+     */
+    assignIssue(key: string, accountId: string): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam-mcp/server",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
   "keywords": [
     "jira",
@@ -41,7 +41,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jam-mcp/launcher": "1.2.0",
+    "@jam-mcp/launcher": "1.3.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"