Service Itsm Agentic Setup Agent Runtime Access Assign

Grant Runtime Access for an Activated ITSM Agent

An ITSM agent (Fulfiller or Employee) can be created and activated, yet fail the moment it's opened — its actions call platform features the user can't execute. This skill closes that gap after activation via two write-capable steps behind one confirmation:

1. Runtime action-execution permissions. Detect which feature permission sets are provisioned, let the user pick a tier per feature (user/agent vs admin) and which user(s) to grant, then assign — license first when license-gated.
2. A custom "Agent Access" permission set. Create (or reuse) Agent Access, grant the activated agents the user chooses (one SetupEntityAccess per agent), then assign it to the same user(s).

The verified feature → tier → permset matrix lives in references/permset-topology.md. No org has all three features — assign only what is provisioned and report the rest as unavailable, never failing on an absent feature.

Every read and write runs through the Salesforce CLI (sf) — no metadata XML, no token extraction, no MCP.

Scope

• In scope: detecting which platform feature permsets are provisioned; per-feature tier selection; asking which user(s) to grant (running user offered, never silent) and resolving them; PSL-then-permset assignment (license-gated tiers) idempotently; creating/reusing the custom Agent_Access permission set; adding a SetupEntityAccess grant per chosen activated agent; assigning Agent_Access to the user(s); verifying assignments by read-back.
• Out of scope (owning skill parenthesized): the Agentforce for IT Service Go toggles / Studio config (service-itsm-agentic-setup-agentforce-studio-configure); creating or activating the Employee (service-itsm-agentic-setup-employee-agent-configure) or Fulfiller (service-itsm-agentic-setup-fulfiller-agent-configure) agent; the Fulfiller activation action-surfacing gap (create/activate-time, not this runtime one — service-itsm-agentic-setup-itsm-agentforce-permset-assign); CMDB access (service-itsm-agentic-setup-cmdb-access-assign); generic non-ITSM permission-set assignment; authoring/editing feature permsets.

Helper scripts (all invoked via Bash) hold every deterministic decision (A9)

Full I/O contracts in references/helper-contracts.md.

• scripts/classify-platform-permset-availability.mjs — which features are provisioned, each tier's present + needsPsl, and the org's own display label per tier.
• scripts/resolve-target-user.mjs — running-user Id from the API-root identity URL (fails closed on a malformed shape).
• scripts/rank-candidate-users.mjs — up to five real, non-service candidate users to offer, ranked by audience (standard-license first for a Fulfiller agent, Unified Employee first for an Employee agent).
• scripts/gate-unified-catalog-tiers.mjs — per target user, which Unified Catalog tiers to offer (Community User → Unified Employee; Admin → System Administrator), else omit UC for that user.
• scripts/classify-activated-agents.mjs — the activated-agent candidate list (BotDefinition InternalCopilot with ≥1 Active BotVersion).
• scripts/classify-agent-access-state.mjs — whether Agent_Access must be created and which chosen agents still need a grant (idempotency).
• scripts/classify-assignment-state.mjs — per user+permset idempotency; pass the sentinel NO-PSL when the selected tier's needsPsl:false.

---

Preconditions

1. sf CLI installed and authenticated to the target org (sf org display -o <alias> shows Connected). All calls use --target-org <alias>; never extract or pass the access token by hand.
2. API v67.0+.
3. node ≥ 18 on PATH.

If a precondition fails, sf surfaces an auth or 401/403/404; report the raw response verbatim and stop — do not fabricate state.

---

Clarifying questions

Ask only what cannot be inferred from conversation:

• Target org — the sf alias. Default to sf config get target-org if unset.
• Target user(s) — never a silent default: if unnamed, ASK via AskUserQuestion (see Phase 2); if named, honor it.
• Tier per provisioned feature — for EACH provisioned feature, ask which tier (lighter user/agent vs full admin); never auto-select.
• Which activated agents — multi-select from the activated-agent list; if only one is activated, still confirm it.
• Confirm the write — one consolidated confirmation covering every write; require an explicit "yes" via AskUserQuestion before any write.

---

Workflow

All calls go through sf; substitute <alias> with the target org. Use the skill's absolute directory for every script path. Exact command shapes: references/cli-invocation.md.

Phase 1 — Read: what is provisioned, and what is activated?

1. Query the six platform feature permsets, capture to a file, and classify:

   sf data query \
     -q "SELECT Id, Name, Label, LicenseId FROM PermissionSet WHERE Name IN ('EinsteinGPTPromptTemplateUser','EinsteinGPTPromptTemplateManager','GenieUserEnhancedSecurity','GenieAdmin','UnifiedCatalogCommunityUser','UnifiedCatalogAdmin')" \
     --target-org <alias> --json > /tmp/itsm-platform-permsets.json 2>/tmp/itsm-platform-permsets.err || true
   node "<skill_dir>/scripts/classify-platform-permset-availability.mjs" /tmp/itsm-platform-permsets.json

   The classifier returns { features, provisionedFeatures, absentFeatures, verdict }. verdict:"ASSIGNABLE" ⇒ ≥1 feature is provisioned; verdict:"NONE-PROVISIONED" ⇒ no feature permset can be assigned (still continue to the Agent Access concern); verdict:"CANNOT-CONFIRM" ⇒ surface the raw error and stop.

2. Query the activated agents (BotDefinition + active-version child subquery), capture, and classify:

   sf data query \
     -q "SELECT Id, DeveloperName, MasterLabel, (SELECT Status FROM BotVersions WHERE Status='Active') FROM BotDefinition WHERE Type='InternalCopilot'" \
     --target-org <alias> --json > /tmp/itsm-agents.json 2>/tmp/itsm-agents.err || true
   node "<skill_dir>/scripts/classify-activated-agents.mjs" /tmp/itsm-agents.json

   verdict:"AGENTS-FOUND" ⇒ present activatedAgents[] for the multi-select; verdict:"NONE-ACTIVE" ⇒ there is nothing for Agent_Access to grant (report it; if NONE-PROVISIONED also holds there is no work — stop).

Phase 2 — Choose target user(s) (never a silent default)

3. Resolve the running user (to offer as a labelled option) and query active org users so a helper can rank real, non-service candidates to offer as ready picks — never proceed with an unstated default:

   sf api request rest "/services/data/v67.0/" --method GET --target-org <alias> > /tmp/api-root.json 2>/tmp/api-root.err || true
   node "<skill_dir>/scripts/resolve-target-user.mjs" /tmp/api-root.json
   sf data query -q "SELECT Name, Profile.Name, Profile.UserLicense.Name FROM User WHERE Id='<userId>'" --target-org <alias> --json > /tmp/itsm-running-user.json 2>/dev/null || true
   sf data query -q "SELECT Id, Name, Username, Profile.Name, Profile.UserLicense.Name FROM User WHERE IsActive = true ORDER BY LastLoginDate DESC NULLS LAST LIMIT 25" --target-org <alias> --json > /tmp/itsm-candidate-users.json 2>/dev/null || true
   node "<skill_dir>/scripts/rank-candidate-users.mjs" /tmp/itsm-candidate-users.json <audience> <userId>

   On verdict:"RESOLVED" keep userId; take its Name from /tmp/itsm-running-user.json for the label; on CANNOT-CONFIRM surface the reasons and stop. If the prompt already named the target user(s) ("grant me" / a username), honor it without asking. Otherwise set <audience> from the agent this grant is for — fulfiller (prefer standard-license users) or employee (prefer Unified Employee users), else any — inferring it from the agent named in the request/handoff or the Phase-1 activated set; rank-candidate-users.mjs returns up to five real, non-service candidates ranked for that audience. Present an AskUserQuestion (multi-select) with those users as direct selectable options — never a plain-prose username request: the running user (labelled "Me — <name>", or just "Me"; recommended) plus the top candidates. The picker allows four options, so offer "Me" + the top three ranked candidates; its built-in "Other" takes any username(s) not listed. Resolve each chosen/typed user by Username (query shape in references/cli-invocation.md, capturing each to its own file); skip inactive/unknown with a note. The confirmed user Ids drive every assignment below.

Phase 3 — Selections (no writes)

4. For each provisioned feature, ask the tier (user/agent vs admin) via AskUserQuestion and record the selected tier's { name, Id, LicenseId, needsPsl }; report each absent feature as "not provisioned on this org — skipped". Unified Catalog is license-shape gated per selected user — run scripts/gate-unified-catalog-tiers.mjs once per user against that user's own capture and offer only its offer[] tiers: Community User only to a Unified Employee user, Admin only to a System Administrator; on omit, skip Unified Catalog for that user as "not applicable for this user's license/profile — skipped" — never offered, never a failed write.
5. Ask which activated agents to add to Agent_Access via AskUserQuestion (multi-select). Record their BotDefinition Ids as a comma-separated list.

Phase 4 — Idempotency reads (no writes)

6. Agent Access state. Query the Agent_Access permset and (only if it exists) its existing BotDefinition grants — capture to /tmp/agent-access.json and /tmp/sea.json (query shapes in references/cli-invocation.md → Phase 4) — then classify against the chosen agent Ids:

   node "<skill_dir>/scripts/classify-agent-access-state.mjs" /tmp/agent-access.json <sea.json|NO-PERMSET> "<chosenAgentIds-csv>"

   Pass NO-PERMSET for the second arg when Agent_Access does not exist yet. The classifier returns { permsetExists, permsetId, missingAgentIds, needsCreate, needsGrants, verdict }.

7. Per user + permset. For each target user × (each selected feature tier and Agent_Access), read existing assignments (PermissionSetAssignment, plus PermissionSetLicenseAssign only when needsPsl:true; shapes in references/cli-invocation.md) and classify. Agent_Access is standalone (needsPsl:false → NO-PSL); a feature tier uses needsPsl from its own row. If step 6 flagged Agent_Access absent (needsCreate:true), skip its keyed PermissionSetAssignment read — no permset ⇒ verdict NEEDS-WRITE; Phase 6 creates it, then assigns by name. Run the keyed read for Agent_Access only when step 6 returned an existing permsetId:

   node "<skill_dir>/scripts/classify-assignment-state.mjs" /tmp/psa.json </tmp/psla.json|NO-PSL>

Phase 5 — Confirm-to-write checkpoint (REQUIRED)

8. Present ONE consolidated summary — every target user, each feature tier to assign (and each absent feature being skipped), whether Agent_Access will be created and which agents it will grant, and every permset assignment — and require an explicit "yes" via AskUserQuestion. On "no", stop and report the planned state with no writes. Assigning a license-gated tier consumes a license seat and takes effect for a live session.