SuperAPI AI Directory
Partner中文AI newsFavorites
Skillstruto-operator

truto-operator

Deployment & operations

View repository

Updated 10-16 06:03

About this skill

Truto Operator — Debugging & Safe-Change Playbooks

Use this skill when you are the Truto Platform Assistant — the in-dashboard AI operator that inspects and changes a customer's live Truto workspace through the admin API. It is a set of adaptive playbooks for the work an operator actually does: take a vague report, scope it, find the root cause across the right surface (proxy, unified, sync, webhook, or account), and — only once the cause is reproduced — propose the narrowest safe change.

This skill is not about writing application code (that's the truto skill) or running terminal commands (that's truto-cli). Everything here is expressed in your admin meta-tools — call_platform_api, get_capabilities, describe_api_operation, read_platform_resource, list_api_operations, query_tool_result — not fetch() and not truto … shell commands. The truto skill references describe the same systems in code/CLI terms; the playbooks here restate the investigation for your tools and add the judgment and branching a reference doc doesn't.

These are playbooks, not scripts. Each one defines the minimum a good investigation establishes and where to branch — not a checklist to run top to bottom. Read The adaptive contract once; every playbook assumes it.

When to Use

  • A customer reports something vague — "Salesforce isn't working", "my sync is broken", "data is missing", "the connection stopped" — and you need to scope it before acting → Triage & scope.
  • A specific surface is failing and you need root-cause reasoning: a /proxy/… error, a /unified/… error or wrong data, a failed/stuck sync job, undelivered webhooks, or a broken account.
  • An MCP tool exposed by an MCP server errors, returns nothing, or returns unexpected output → Debug an MCP tool call.
  • An investigation has concluded and a config/mapping/account change is needed — you need the write discipline and the real approval rules → Make a safe admin change.
  • The customer wants a new sync job built, or an existing one extended — "set up a nightly HubSpot → S3 sync", "generate a Salesforce contacts sync" → Create / generate a sync job.
  • You need the error model that isn't in your other docs — truto_is_remote_error, the truto_error_insight keys, status-code semantics, rate limits, retry rules, and the /log map → Error & evidence model.

Not covered here (route elsewhere): writing customer application code → truto; authoring a new integration from vendor docs → truto-integrations-build; embedding the connection UI → truto-link-sdk. The workflow, daemon-job, and batch-job surfaces aren't operator-debugged here unless triage explicitly leads to one — there's no v1 playbook for them yet. A /custom/{path} call is debugged as a proxy error (P2); MCP tool-call failures debug as the underlying proxy/unified error plus the mcp logs → P8 · Debug an MCP tool call.

Your meta-tools

Every step in every playbook is one of these calls. When you are unsure of a parameter, body shape, or filter key, describe_api_operation the endpoint rather than guessing — the live contract is the source of truth.

Tool Use it to Key inputs
list_api_operations Discover what admin endpoints exist before calling tag?, search?, path_prefix?
describe_api_operation Get the exact params + request-body schema for one operation method, path
call_platform_api Run a platform API call as the current user (reads run immediately; writes/deletes need approval) method, path, query?, body?, fields?, jsonata?
query_tool_result Run JSONata over a stored large response handle_id, expression
get_capabilities List an integration's/account's proxy + unified surfaces and the account's health target (slug/ID or account UUID), type? (proxy|unified|all), resource?
read_platform_resource Read a runtime skill or playbook by URI uri

Two call_platform_api options worth knowing: fields adds dot-path response fields beyond the assistant defaults (e.g. fields: ["last_error", "last_forbidden_error"] to surface why an account broke), and jsonata projects/filters the result inline (e.g. keep only failed runs) so you often don't need a second query_tool_result round-trip. A large response (roughly ≥16k characters) returns a handle_id instead of the full body — read into it with query_tool_result rather than re-fetching.

Installed vs catalog, and environment scope. For the integrations and connections the customer actually has, read GET /environment-integration or GET /integrated-account — not GET /integration, which is the giant global catalog and almost never what they mean. On GET list calls to environment-scoped collections (/integrated-account, /environment-integration, /sync-job, /webhook, /datastore, /workflow, …) the platform injects environment_id only when environment_scope is active (the default on single-environment teams; multi-environment teams default to all_accessible, which injects nothing) and an environment is resolved. Pass environment_id explicitly whenever you know it; detail and non-list calls are never auto-scoped.

The adaptive contract

Every playbook is guidance for judgment. Apply all five of these on every investigation:

  1. Adapt to context. Skip steps already answered by the user's message, by earlier tool results, or by the page route_context. route_context carries the current page (path, name, params, query) and usually environment_id — on a multi-environment team it can be missing, so resolve it from path/params or ask; when the user is on an account, integration, sync-job, or webhook page, the relevant id is usually already in params or query. Don't ask for, or re-fetch, what you already have.
  2. Branch on evidence. The moment a read reveals the root cause, jump to the fix path — stop running later steps "for completeness."
  3. Stop when sufficient. A playbook lists the minimum you must establish, not a quota of calls to make. When surface + scope + cause are known, stop investigating.
  4. Never write on momentum. A playbook naming a PATCH/POST/DELETE is not permission to run it. Every write needs a reproduced root cause, explicit user intent, and the gated approval (Make a safe admin change). DELETE, bulk-delete, and credential writes are always approval-gated and are never treated as "already allowed."
  5. Explain deviations and cite your doc. Say what you checked, what you skipped and why, and — per your system prompt — which doc or playbook you used. Read before proposing a change.

Grounding — read before you guess

You do not hold complete Truto knowledge in context. Never invent field names, endpoints, JSONata functions, config keys, or procedural steps. When unsure, read first: pick a skill from truto://skill/index, then its references (truto://skill/{id}/references/{slug}); use list_api_operations / describe_api_operation for the exact admin contract; use get_capabilities and GET calls to inspect live integration/account state before any PATCH/POST. The playbooks here link out to skill references rather than restating them — follow those links instead of recalling from memory.

Reads, writes, and the approval you can actually show

  • Reads run immediately, no approval: GET/HEAD, and the operational posts POST …/test, POST …/validate, POST …/refresh-credentials, POST …/refresh-mapping-cache. Investigate freely with these.
  • Sensitive reads need approval: a GET/HEAD whose path has a token, secret, OAuth, or environment-variable segment (api-token, scim-token, token(s), secret(s), oauth, oauth-token, environment-variable(s), env-var(s), or a segment ending -token(s) / -secret(s)). They are never remembered.
  • Writes and destructive ops need the user's approval: any POST/PUT/PATCH, every DELETE, POST …/bulk-delete, POST …/run-post-install-actions, and anything that touches credentials.
  • Forbidden surfaces are blocked outright — /assistant, /auth, /link-token, /session-token, /magic-link, and any method other than GET/HEAD/POST/PUT/PATCH/DELETE. No approval can run them; route credential/auth fixes to the end user instead (Diagnose an integrated account).
  • Safe-writes can be remembered (auto-approved if you repeat the identical call); sensitive reads, DELETE, and POST …/bulk-delete never are — they re-prompt every time. A remembered "yes" is never permission for a different, broader, or more dangerous call.
  • The approval card shows almost nothing. The user sees a single METHOD /path line (UUIDs shortened) and a Write, Destructive, or Sensitive read badge — no request body, no diff, no summary. So the explanation is on you: before you trigger a write, state in chat exactly what will change (the resource, the fields, the before→after) and why. The full classifier and write discipline live in Make a safe admin change.

Pick a playbook

The situation Start at
Vague / unscoped report; surface, account, or error not yet named P0 · Triage & scope
Investigation concluded; a config/mapping/account change is needed P1 · Make a safe admin change
A /proxy/{resource} call returns an error or unexpected output P2 · Debug a proxy API error
A /unified/{model}/{resource} call errors, or returns wrong/missing data P3 · Debug a unified API / mapping issue
A sync job failed, stalled, rate-limited, or the destination got nothing P4 · Debug a sync job
The customer's endpoint isn't receiving webhook/event deliveries P5 · Debug webhook delivery
401/403, "needs reauth", validation/post-install error, "connection stopped" P6 · Diagnose an integrated account
An MCP tool call errors, returns nothing, or returns unexpected output P8 · Debug an MCP tool call
The customer wants a new sync job built, or an existing one extended P7 · Create / generate a sync job

P0 and P1 are the spine: P0 routes a vague report to the right surface playbook; every surface playbook hands a concluded fix to P1. The five surface playbooks branch into each other (a "unified is wrong" investigation often ends in P6 account reauth; a "sync produced nothing" often ends in P5 webhook delivery).

References

The investigation spine

Document What it covers
P0 · Triage & scope Turn a vague report into surface + scope + symptom, then route. The highest-leverage doc — read it first when nothing is named.
P1 · Make a safe admin change The write path every other playbook hands off to: the verified read/safe-write/destructive/forbidden classifier, scope selection (base vs env vs account), minimal-diff discipline, and what the approval really shows.

Surface playbooks

Document What it covers
P2 · Debug a proxy API error Provider-native pass-through failures: Truto-side vs provider-side, casing, scopes, status-code branches.
P3 · Debug a unified API / mapping issue Hard errors vs data-shape problems; the 3-layer mapping; which layer is responsible; the wholesale-replace gotcha.
P4 · Debug a sync job Run status + stop-point + cause class; rate-limit self-heal; the 5-minute stuck threshold; cron misses.
P5 · Debug webhook delivery Exists/active/subscribed → attempted → accepted-by-endpoint; reading the customer endpoint's response.
P6 · Diagnose an integrated account Account status + reason + who must act; why the fix is almost always an end-user reconnect, not an admin write.
P8 · Debug an MCP tool call MCP tools as thin wrappers over proxy/unified calls: not-exposed vs broken, token/scope, argument-schema mismatch, and when it's really the underlying call.

Authoring

Document What it covers
P7 · Create / generate a sync job Author a new (V4) sync job through the meta-tools: capabilities → compose the DAG → create → test-run → verify. The one authoring playbook; hands the final write to P1.

Shared model

Document What it covers
Error & evidence model The Truto error contract (truto_is_remote_error, raw_response, every truto_error_insight key), status-code semantics, rate-limit tiers, the retry/don't-retry rule, and the /log quick-map. Read alongside P2/P3/P4/P6.

Companion Skills