6.14 Resource formats and internal interfaces

These formats correspond to Community 0.2.8 resource imports and internal communication. Recheck readers when upgrading; business-system invocation is documented separately in the employee API guide.

Common resource formats

Format	Purpose	What to check
teloa.business-package/v2	Business package resource list	Resource identities, locked versions, relationships, and scope
teloa.business-package/v3	Business package with model dependencies	Fixed model declarations and readiness at each entry point
teloa.business-package/v4	Business package that may include a complete configuration	Only v4 supports business-configuration; requires alpha.7 or later
teloa.business-dashboard-resource/v1	Reusable business dashboard resource	Fixed identity and version, complete configuration v2, closed page and definition references; excludes records, synchronization bindings and default actions
teloa.role/v1	AI employee role template	Duties, data and execution scopes, and five responsibility groups
teloa.work-template/v1	Task template	Input requirements, output, and locked skill references
teloa.mcp-connection/v1	MCP connection definition	serverName and the tool set
teloa.reference-list/v1	MCP reference list	Sources, byte counts, and SHA-256 versions
teloa.reference/v1	MCP read result	Content and source for the same version

A resource package's scope defaults to domain. Referenced versions must match resource definitions. Do not use JSON field order to determine object equality.

Share subjects

teloa.template-share/v2 distinguishes employee (exactly one employee), team (at least two), app (no employees; includes a skill, MCP connection or extension), and skill (exactly one skill). Connections can also use mcp. Its files include the UTF-8 body of teloa.json, using business-package/v2, v3 or v4. Identity and fixed version agree across layers; required people/automation/connections/business capabilities are declared. There is no standalone app catalog kind, while the share format has an explicit app subject.

Legacy teloa.template-share/v1 retains its original single-employee reader. Shared employee definitions omit runtimeConfig, a stricter boundary than standalone role imports below. See sharing for examples and distribution.

AI employee templates

teloa.role/v1 is Teloa's current role template import format. AI Worker Standard 1.0 describes workers, work contracts and collaboration rules. The standard and this product import format are maintained separately: a standard exchange document is not directly a role template, and unsupported fields cannot be added to this format.

The template uses name, kind, duty, dataScope and executionScope to describe identity, duties and scope. Creating or editing an employee now requires an explicit responsibility object containing these five string arrays:

Field	Meaning
triggers	Triggers: when to take on work
autonomousActions	Autonomy: what can be done within existing authorization
confirmationPoints	Confirmation: which steps require confirmation
escalationRules	Escalation: how to report or hand over missing information, conflicts or scope limits
deliveryChecks	Delivery: what the result includes and how completion is checked

All five fields must be present; each accepts at most 30 entries of up to 1,000 characters. Arrays may be empty, and an empty array grants no additional authority. Current templates have expanded structured responsibilities while retaining the teloa.role/v1 file format number. For older templates without the entire responsibility object, the reader supplies five empty arrays rather than generating duties. New templates should explicitly state the responsibilities relevant to the role.

This example uses English instructions and preserves existing authorization and required confirmations after import:

{
  "format": "teloa.role/v1",
  "name": "Research Assistant",
  "kind": "employee",
  "duty": "Summarize supplied material and distinguish evidence from open questions.",
  "dataScope": "Only supplied material and already authorized references.",
  "executionScope": "Read and draft within existing authorization; retain required confirmations.",
  "responsibility": {
    "triggers": ["When assigned a summary of supplied material."],
    "autonomousActions": ["Read authorized material and draft a source-based summary."],
    "confirmationPoints": ["Ask before expanding the authorized data or execution scope."],
    "escalationRules": ["Report missing or conflicting evidence without inventing conclusions."],
    "deliveryChecks": ["Include sources, findings, open questions and incomplete work."]
  },
  "runtimeConfig": {
    "agentPresetId": "teloa-standard"
  }
}

runtimeConfig is optional. A template may carry an agentPresetId; the receiving host still checks preset availability during preparation. Template model and fallbackModel selections are ignored rather than inherited. The owner selects and configures models and accounts on the receiving host.

A role template does not carry instance scopes, skills, knowledge, credentials or grants; these fields cannot be inserted into this file. Related resources are bound through the package manifest and the receiving instance. Importing a definition does not connect accounts, start work or expand authority.

Business dashboard definitions and query limits

Business dashboards add three business definitions. Like record types, views and actions, they go through three steps in order: conversation draft, preview and owner confirmation, and their readers validate fields strictly:

Format	Purpose	What to check
teloa.business-source-mapping/v1	Data source mapping	The source must be a business data port, a read-only managed MCP tool, or AI employee results; JSONPath subset, 1–3 primary keys, deletion semantics, sync schedule
teloa.business-widget/v1	Dashboard widget	Seven widget kinds; SQL may reference only record types defined in the scope (table name with - replaced by _) and their fields; charts are Vega-Lite specs with allow-listed keys
teloa.business-dashboard/v1	Dashboard	12-column grid, referenced widgets, refresh schedule (intervals under 60 seconds require acknowledgeShortInterval: true; under 10 minutes the page warns about external quota and local resources)

Widget SQL first passes a syntax-tree allow list (a single SELECT, allow-listed functions and nodes; schema names, system tables, placeholders and multiple statements are rejected). It is then rewritten into a parameterized query over the current versions in the snapshot table for the owner and scope, and runs only after a second validation and a round-trip check. Execution uses the read-only role teloa_business_reader over a dedicated connection pool: 5 seconds per query, at most 10,000 rows, 1 MB per row, 8 MB in total, and 5 concurrent queries per scope (per process). In the rewritten query, the snapshot table and the safe conversion functions are qualified with the schema that holds the Teloa tables (the application connection's current_schema(), public in the personal edition). The allow-list constants are in packages/backend/src/work/business-sql-whitelist.ts, and the matching database tests are in packages/backend/tests/business-sql-guard.test.ts, business-sql-rewrite.test.ts and business-sql-executor.test.ts.

The draft tool derives its request identity from the instruction, the definition kind and the definition id: replaying the same definition replaces the same draft, and one instruction can save several different definitions. The returned content body is compared as canonical text (keys sorted), so field order does not matter.

Unknown fields and corrupt data

Many readers enforce strict field validation. Misspelled fields are not silently ignored. Treat invalid input and corrupt stored data separately: correct the input in the first case; preserve evidence and repair from a trusted backup or source in the second.

Internal RPC

The client sends internal RPC requests through the Harness. Endpoints, request envelopes, authentication cookies, and response parsing can change between versions. Requests captured in a browser should not be treated as a stable third-party REST interface.

Business systems call employees through the employee work API, SDK and MCP Server. Employees access external reference services through the supported MCP path. Verify identity, grants and request boundaries separately for each direction.

Project interfaces

The internal projects/list, projects/get, projects/create, projects/edit, and projects/candidates endpoints share the project contract. The authenticated session determines ownership. Creation uses a request UUID; edits require expectedVersion and reject conflicting updates. The business scope is immutable after creation.

Project links use task, group, role, plan, resource, or artifact plus a record ID. Only available records within the permitted scope can be newly linked. Detail responses derive task progress and deliverables from the linked records. Linking is not an execution authorization and does not change the original records.