Aevatar automation

scheduled_agent_creator (scheduled Ornn skill agents)

Use scheduled_agent_creator to create a new caller-owned scheduled automation agent from an Ornn skill reference, or to create a single delayed reminder.

This tool is for an independent scheduled Ornn skill agent or a one-shot reminder. It is NOT an alias for Studio Team member automation. If the thing being scheduled is an already-bound Team member workflow, the canonical path is aevatar_schedule_member_workflow or /api/scopes/{scopeId}/teams/{teamId}/members/{memberId}/automations — see aevatar-scheduler. Do not route a Team member here, and do not route an independent skill agent to generic /api/schedules.

For recurring automation, set schedule_mode="cron" and provide skill_ref, schedule_cron, and schedule_timezone; optional LLM tuning fields are allowed. If the loaded skill body will call connected NyxID services through nyxid_proxy beyond Ornn and the Lark outbound channel, declare them with the typed requirement contract:

required_nyx_services[] = { user_service_id, service_slug_snapshot }

The exact user_service_id is the authorization; the slug snapshot is an integrity/display value and can never substitute for it. nyx_user_service_id identifies the exact outbound provider where applicable. The older required_service_slugs contract has been removed — do not recommend it, and never infer a UserService ID from a slug, a vendor name, or a catalog service ID (a connected UserService ID and a catalog service ID are different identifiers and are not interchangeable).

If the scheduled agent needs deterministic fire-date fields, its execution prompt may use the same fire-time Chat template as other schedules: {{@schedule.run_date}}, run_year, run_month, days_until_month_end, fire_at_utc, and timezone. The prompt must then be valid JSON and each placeholder must be inside a JSON string value. The values come from the authoritative logical fire and configured IANA timezone; catch-up keeps the original occurrence and run-now uses the manual instant. Unknown placeholders or invalid JSON fail closed. A manual run is not cron-rearm proof.

For one-shot delayed reminders such as "remind me in 10 minutes" or "later today tell me ...", set schedule_mode="one_shot" and provide exactly one of delay_seconds or run_at_utc, plus one_shot_message. Prefer delay_seconds when the user gave a relative delay. Do not use code_execute with sleep, timers, polling loops, or long-running scripts for delayed one-shot requests; durable delivery must go through scheduled_agent_creator. Do not publish an Ornn skill just to send a one-shot natural-language reminder unless the user explicitly asks for reusable automation or the reminder requires a real skill workflow.

Do not provide owner, scope, Lark target, Nyx provider slug, API key, service IDs, inline skill content, or outbound credential fields. This write command does not request remote approval; the tool derives context from the current authenticated/channel turn, mints a scoped NyxID key, and returns only an accepted receipt or a typed tool error.

skill_ref must be unversioned for now. A name@version reference returns versioned_skill_ref_not_supported_yet.

The scheduled agent's credential is a dedicated Agent Key

A scheduled_agent_creator agent does not run on a replayed user bearer, and it does not run on a fire-time broker token. The tool derives caller and ownership from trusted context, plans and revalidates typed authorization, provisions a constrained dedicated Agent Key, stores the raw material in the Vault, persists a typed reference, returns an accepted receipt, and delegates later management to agent_builder.

Secret custody. Raw key material is written only to ISecretVault. Durable state, committed events, read models, logs, tools, and public APIs expose only stable non-secret facts: a typed credential reference, Agent Key ID, expiry, authorization fact, and credential generation. The workflow borrows a durable credential reference; every operation that needs the credential late-resolves it through the Vault at the moment of use, fail-closed for an absent, expired, revoked, mismatched, or malformed reference. Never ask the user to paste the key, accept it in JSON, print it, store it in an Ornn package, or reconstruct it from an ID.

Grants are exact and closed: allow_all_services = false, allow_all_nodes = false. Only the targeted plan supplies allowed service IDs and node IDs.

Expiry. The scheduled agent's default Agent Key lifetime is 90 days, subject to its typed authorization policy and deployment configuration. Describe the projected expiry — never promise an eternal key, and never quote a minutes-scale TTL for this credential class.

Lifecycle. Adding a new external service dependency is a reauthorization, not an edit: new preflight → new confirmed plan → provision a replacement generation → commit it → only then revoke the old generation. Never mutate an existing key in place to widen its authority. Pause and resume preserve the active credential and are neither a revoke nor a reauthorization. Delete tracks NyxID key revocation and Vault secret revocation as independent durable tracks, and a retry reuses the original delete operation identity rather than synthesizing a new one.

202 / accepted is admission only

An accepted receipt or pending status proves command/effect admission — nothing more. It does not prove credential issuance completed, the Vault write completed, activation committed, the read model observed the new state, cron fired, or the workflow succeeded. Reread the canonical owner-scoped record and require a newer authoritative stateVersion. Note that credential health (authorizationStatus == active) and firing state (enabled == true) are independent dimensions.

If authorization planning returns authorization_catalog_route_unresolved or api_key_scope_plan_route_unresolved, treat it as non-retryable. Preserve the exact required UserService IDs, stop refresh/retry loops, and repair or deactivate the unresolved route before trying again. A required ID may merely share a catalog family with the bad active peer; do not delete or reconnect unrelated services.

Token classes: verified lifetimes, not folklore

Never quote one class's lifetime for another. The 300-second broker TTL below belongs to the NyxID binding-exchange source used by generic schedules — it does not describe a dedicated Agent Key.

Credential	Lifetime	Authority to cite
Dedicated scheduled-invocation Agent Key (credentialSourceKind = scheduled_invocation_agent_key)	Policy-governed; scheduled agent default ~90 days	the record's credentialExpiresAtUtc + credentialGeneration
Generic-schedule caller credential via NyxID binding exchange at fire	300 s, fixed	NyxID oauth_broker_service.rs BROKER_ACCESS_TTL_SECS
Interactive user login access token	deployment config JWT_ACCESS_TTL_SECS (code default 900 s; production instances often set hours)	decode the actual JWT: exp − iat
NyxID delegated / MCP delegation token	300 s	NyxID crypto/jwt.rs
NyxID service-account token	SA_TOKEN_TTL_SECS (code default 3600 s)	NyxID config.rs
Lark tenant_access_token	≈2 h, cached and refreshed transparently by NyxID	NyxID Lark token-exchange service description
aevatar scope service token	TokenLifetimeMinutes (default 60 min)	aevatar Aevatar.Authentication.ScopeServiceTokens/ScopeServiceTokenOptions.cs

Anti-hallucination protocol for token_expired / 401 in a scheduled run — complete these steps before naming any cause:

1. Never assert a token lifetime from memory. Read it: decode the JWT actually in hand (exp − iat; report only the numbers, never print the token), or cite the owning repo's constant from the table above.
2. Read credentialSourceKind before anything else. This single field decides which diagnosis applies, and getting it wrong is the most common failure in this area:
   • scheduled_invocation_agent_key ⇒ a dedicated Agent Key. Do not diagnose a fixed five-minute broker expiry merely because the call was scheduled. A token_expired six minutes after fire on this source is not explained by the 300 s constant, and the ~5-6 minute coincidence is not evidence. Inspect instead: key credentialExpiresAtUtc; Vault resolution and reference integrity; committed caller authority; the authorization fact; the exact service/node grants versus what the failing step actually called; credentialGeneration (did a reauthorization replace it mid-flight?); revocationPending / nyxIdRevocationStatus / vaultRevocationStatus; then the downstream service's own token.
   • nyxid_binding_exchange (generic schedules) ⇒ the fire-time broker token is the right hypothesis; identify the actual exchanged token and use its verified iat/exp.
3. Identify the token class first. "The access token lives 8 hours" (login class) and "the run credential lives 5 minutes" (binding-exchange class) can both be true — about different tokens. A claim that conflates them is wrong even if each number is right.
4. Correlate failure onset with FIRE TIME, not wall clock — but only once the source is known. For a binding-exchange source, failures beginning ~5 minutes after fire in every run ⇒ the fire-time-minted broker credential aged out. Failures at one fixed wall-clock moment across runs ⇒ something else (provider-side expiry or rotation).
5. Separate blast radius. If ALL NyxID-authenticated steps fail after some instant, the run caller credential died. If only one step type fails while sibling proxied steps still succeed, suspect that step's own credential path instead.
6. Report observed timestamps/status as fact and everything else as labeled inference. Any number you did not verify in this session is an inference.
7. Never emit secret material in any diagnosis, log excerpt, or artifact: no raw Agent Key, bearer/access/refresh/delegation/service-account token, Vault reference or ciphertext, permission digest, unfiltered API-key inventory, or authorization header. Stable resource IDs may be reported for management or cleanup, never as secret material.

Long-running task automation playbook

Use this playbook when the user asks for a recurring, scheduled, monitored, or otherwise long-running task instead of a one-off answer. Typical triggers include: "每天...", "每周...", "each week...", "monitor X and tell me...", "定时...", "recurring", "keep watching", and "长期跟踪".

Workflow creation semantics

When a Lark user asks to create a workflow that should be runnable, page-visible, or invokable later by workflow id, create or update a Scope Workflow through the available Scope Workflow command tool path. Ornn publishing is for reusable templates/packages/exports; it does not make a workflow page-visible or runnable in Aevatar until the template is mounted/imported into Scope Workflow and the accepted/readmodel propagation contract says it is visible.

1. Recognize the request as automation.

   • Do not answer with a one-shot summary if the user wants repeat runs.
   • Do not ask the user to hand-write the skill package.
   • Treat the future runner as a runnable Ornn skill, not a chat-only script.

2. Reuse before you author — search Ornn first.

   • Before authoring anything, call ornn_search_skills with the task's distinctive capability keyword. Prefer a single strong keyword (deadline, attendance, reimbursement, digest, candidate); multi-word phrase queries match poorly, so if a phrase returns nothing, retry with one keyword or mode=semantic before concluding nothing exists.
   • A skill named like <capability>-…-payload-builder is a reusable match even if its name is longer than what the user said; do not require an exact name.
   • If a returned skill already covers the request, load it with use_skill, then go straight to negotiation and schedule it with scheduled_agent_creator using that existing skill_ref — no authoring or publishing needed. Do NOT author a duplicate of a skill that already exists.
   • Only author a new skill when the search returns no suitable match.

3. Author a runnable skill package yourself.

   • Build the package as an active playbook: the skill must collect data with its own tools, analyze the current facts, then deliver the result to Lark.
   • For monitoring or digest jobs, use the loaded skill metadata and instructions to choose the monitoring or digest flow: fetch live data through nyxid_proxy for explicit connected services such as api-github, derive the digest from current facts, then post the digest to the negotiated chat target.
   • Write instructions_markdown as executable guidance, not passive description. Use workflow_yamls and scripts whenever they make the flow deterministic or easier to reuse.
   • Keep the package typed: name, description, version, category, instructions_markdown, plus any workflow_yamls and scripts the run needs.

4. Negotiate schedule and output with an interactive Lark card.

   • Use reply_with_interaction to ask for the minimum missing details.
   • Ask for the execution cadence as a concrete schedule (cron plus timezone), not vague wording.
   • Ask where the result should go: direct message or group chat.
   • Ask for the output format: plain text or Feishu cloud doc.
   • Prefill anything you can infer from the current conversation, and only ask for what is missing.
   • If the user changes frequency, time, delivery target, or output format, reopen the same negotiation instead of scheduling against stale values.

5. Publish the skill, then schedule it.

   • Call ornn_publish_skill with the assembled typed package.
   • If publish fails, inspect the diagnostics, fix the package, and retry.
   • Ornn private skill publishing executes directly. Do not say it is waiting for remote approval unless a typed remote approval result explicitly says so.
   • Do not tell the user a skill was submitted, uploaded, or published unless the ornn_publish_skill call actually returned a success receipt for that skill.
   • Once the skill is published successfully, call scheduled_agent_creator with the published skill_ref, the agreed schedule_cron, the agreed schedule_timezone, and required_nyx_services entries carrying the exact user_service_id (plus its service_slug_snapshot) for every connected service the skill body will call through nyxid_proxy.
   • Carry the negotiated delivery/output choice into the runner's execution_prompt and outbound delivery setup; if the chosen delivery target differs from the current conversation, rebind it with agent_delivery_targets using the returned agent_id.
   • For plain text output, the skill should send a concise digest back to Lark. For Feishu cloud doc output, the skill should create or update a document and return the link.

6. Recover cleanly.

   • Publish failure means the package is wrong; refine and republish.
   • User rejection or edits mean the negotiation is not stable yet; update the card and retry.
   • If the user later wants a different cadence, treat it as a new negotiation for a new schedule rather than pretending the existing schedule changed automatically.

agent_builder (Day One persistent automation lifecycle)

agent_builder manages the lifecycle of agents the user has already created. It can list, inspect, run, pause, resume, and delete; it does not create agents.

Intent	Slash command
List agents	/agents
Inspect one agent	/agent-status <agent_id>
Manual run	/run-agent <agent_id>
Pause schedule	/disable-agent <agent_id>
Resume schedule	/enable-agent <agent_id>
Delete (two-step)	/delete-agent <agent_id> confirm

Tool semantics: disable_agent pauses scheduled execution without deleting; enable_agent resumes; delete_agent disables, revokes the NyxID API key, and tombstones the registry entry. The Nyx relay path handles these slash commands directly without an LLM round-trip — you typically only see these flows when the user asks for them in natural language.