paperclipai/paperclip · error

trustPreset.detail

Error message

trustPreset.detail

What it means

On GET /api/agents/me, after the special key-scope branches, the route resolves the caller's self-view trust preset via `resolveAgentSelfTrustPreset`. When the preset resolves to kind "denied", the route returns HTTP 403 with the preset's `detail` string as the error message. This means the agent actor's trust level does not permit a full self-detail view; the trust preset itself decides both the denial and the human-readable reason sent to the client.

Source

Thrown at server/src/routes/agents.ts:3789

    }
    if (
      req.actor.keyScope?.kind === "task_bridge"
      || req.actor.keyScope?.kind === "skill_test"
    ) {
      res.json({
        id: agent.id,
        companyId: agent.companyId,
        name: agent.name,
        role: agent.role,
        title: agent.title,
        status: agent.status,
        keyScope: req.actor.keyScope,
      });
      return;
    }
    const trustPreset = await resolveAgentSelfTrustPreset(req, agent);
    if (trustPreset.kind === "denied") {
      res.status(403).json({ error: trustPreset.detail });
      return;
    }
    if (trustPreset.kind === "low_trust_review") {
      res.json(buildLowTrustSelfView(agent));
      return;
    }
    res.json(await buildAgentDetail(agent));
  });

  router.get("/agents/me/inbox-lite", async (req, res) => {
    if (req.actor.type !== "agent" || !req.actor.agentId || !req.actor.companyId) {
      res.status(401).json({ error: "Agent authentication required" });
      return;
    }

    const issuesSvc = issueService(db);
    const recoveryActionsSvc = issueRecoveryActionService(db);
    const rows = await issuesSvc.list(req.actor.companyId, {

View on GitHub (pinned to 01ad858492)

Solutions

1. Read the `detail` message in the 403 body — it names the specific trust-preset reason; act on that.
2. Have a board operator review/raise the agent's trust preset configuration if full self-detail access is intended.
3. Fall back to the low-trust self view (buildLowTrustSelfView surface) or the limited key-scope branch data the agent is entitled to.
4. Re-issue the agent key with the correct scope/trust tier if the key's scope no longer matches its intended use.
5. Check recent config/feature-flag changes to trust presets around the time the error started.

Example fix

// before: client assumes /agents/me always returns full detail
const me = await api.get('/agents/me');
// after: handle the denied/low-trust variants
const res = await fetch('/agents/me', { headers: auth });
if (res.status === 403) return useLowTrustSelfView(); // render limited view from body.detail
const me = await res.json();

// probe the self endpoint and degrade gracefully
const res = await fetch('/api/agents/me', { headers: agentAuth });
if (res.status === 403) {
  const { error } = await res.json();
  console.warn('self detail denied by trust preset:', error);
}

type TrustPresetDecision = { kind: 'allowed' } | { kind: 'low_trust_review' } | { kind: 'denied'; detail: string };
function isDenied(p: TrustPresetDecision): p is { kind: 'denied'; detail: string } {
  return p.kind === 'denied';
}

try {
  return await api.getAgentSelfDetail();
} catch (err) {
  if (err.status === 403) return buildLowTrustSelfViewFromError(err); // limited view
  throw err;
}

When it happens

Trigger: An authenticated agent (bearer key, non task_bridge/skill_test scope) calls GET /agents/me while resolveAgentSelfTrustPreset returns { kind: "denied", detail } — e.g., the agent's trust preset configuration disallows self-detail reads for its current trust tier/key scope.

Common situations: An agent with a restricted trust preset calling the full self endpoint instead of the low-trust view; trust preset config changed server-side (or via env/feature flag) after the key was issued; calling /agents/me with a key whose trust tier was downgraded; CLI/adapter SDK still using an endpoint the agent's preset no longer allows.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

• Run telemetry is outside this actor's authorization boundary
• Runtime service control is outside this actor's authorizatio
• Plugin UI is not available (status: ${plugin.status})
• Access denied
• DUPLEX_CHANNEL_CAPABILITY_DENIED

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/fbaf9f3572ed6c2f. Report an issue: GitHub.