Resource APIs in the built-in agent
The built-in agent's resource API catalog is collected from the server's registered routes, including routes enabled by deployment flags. It is not a separately maintained copy of the HTTP API.
The built-in agent can create agent definitions, which are first-class runnables rather than sessions. Ask, for example:
Create a Reviewer agent in my project, using this memo as its instructions and the Review skills folder as its optional skills.
dreamlake_agents_create accepts name, optional namespace, description,
projects and tools. Instructions are either markdown, or
instructionNoteId plus optional skills entries with kind (note or
folder) and id. The canonical runnable route checks the caller's resource
permissions and performs project filing. The result contains the runnable ID
and its Agents editor link; creation does not launch a session.
Choose tool permissions
Open the Permissions popover in agent chat, or the matching control in Built-in agent settings. Choose Read only to inspect resources without changing them (connected apps may still prepare actions for review), or Full access, the last option, to enable changes and administrative tools within your existing permissions. The Eye and ShieldAlert icons identify the two levels; a checkmark identifies the selected level. Opening or dismissing the popover does not change permission. Arrow keys move focus; Enter, Space or a click selects the level.
The choice applies to the next message; it does not cancel or revoke an already admitted turn. Connected apps have a separate switch. The choice is saved for your signed-in account in this browser and is shared by chat and settings. It does not create a Project delegation, connect an app, apply a host policy, or remove an action's existing confirmation requirement. Agent definition tool restrictions and current resource permissions still apply. This selector does not yet provide persistent per-agent or per-session permission overlays.
Diagnose Project access
Human Project ADMIN, the built-in agent's persistent Project delegation, and the
turn's enabled tools are separate permissions. A folder write can be denied even
when the human is an administrator. Use dreamlake_agent_project_access with the
verified namespace and full projectId to inspect these layers. The read-only
diagnostic requires human read access, works without an agent Project grant, and
reports only the caller's own agent. It cannot change access.
A human administrator can explicitly save READ or WRITE delegation for one Project through the personal-agent delegation API. The model cannot invoke that API's mutations. Enabling write tools alone does not save a delegation. Organization-scoped turns can use exact delegated Projects in that organization, subject to current human access; personal or other-organization grants are not inherited. A diagnostic is a snapshot: execution checks access again.
Memo filing has a separate caller-permission path. Inspect the Memo's current filing permissions before concluding that a Project tree denial blocks filing. Keep the requested namespace and verified IDs; never silently create or search in a personal workspace as a workaround for denied organization access.
The diagnostic accepts operation: "readProject" or "createFolder" (the
default). Its accessAction is null when that operation is available, or one
scoped action identifying the Project and required capability or delegation.
For example, a human administrator with an agent READ grant receives a WRITE
delegation action for folder creation. A caller who also lacks human write
access receives an administrator action instead. The diagnostic never grants
access, and a successful read of it does not imply the requested write is allowed.
Moving Memos and artifacts
dreamlake_move_preflight checks explicit source and destination endpoints.
Each endpoint contains a namespace and optional verified projectId;
kinds contains note, artifact, or both. Set createDestinationFolder when
the requested placement needs a new folder or Bindr. The tool is read-only and
checks the caller's own agent delegation, without enumerating other agents.
Its result is advisory: each mutation still checks current authorization.
Project-only moves do not require namespace ownership authority. Filing a
Memo in another Project retains its owner and existing filings. A missing
folder grant does not establish that caller-authorized Memo filing is denied.
Individual Memo filing/location previews use dreamlake_notes_move with
dryRun: true; artifact filing uses its discovered canonical API.
For cross-namespace ownership changes, preflight reads both namespaces'
advertised capabilities. Disabled artifact transfer is reported as unsupported,
with accessGrantWillFix: false. Memo metadata transfer and preserving transfer
are separate capabilities: the exact per-Memo dreamlake_notes_transfer_preview
determines whether its access and filings can be preserved. Preflight never
authorizes a transfer or relaxes that policy. Unknown or inaccessible capability
responses are inspection failures, not proof that a feature is disabled.
Transfer previews carry the ownership and sharing consequences for review. Submission retains that exact review and idempotency key. Recipient acceptance remains separate; a pending request is not a completed move. Blocked previews and pending transfers have distinct tool outcomes even when the HTTP request succeeds. Readback verifies stable resource IDs, owner, filing/location and transfer completion; partial results retain their completed steps.
Within a turn, an unchanged request that already received a deterministic access or unsupported-transfer denial is suppressed before another execution. A changed request still undergoes normal checks. A relevant successful Project access or transfer capability observation permits one new attempt when no earlier observation exists. If execution still fails, rereading the same snapshot does not permit another attempt: relevant access or capability values must change. Unrelated diagnostics do not reset suppression. Every permitted attempt still checks authorization at execution. No grant, content or session is changed by preflight or retry suppression.
Sending and steering
The built-in composer moves submitted text into the conversation immediately, before server acknowledgement. A rejected send restores the original input if it has not been edited; otherwise the unsent message stays visible alongside the newer draft. Consecutive assistant segments share one text block and one copy button below it. Message boundaries do not create line breaks; explicit newlines in the answer do.
While a turn is running, Enter sends a steering message. It keeps the same conversation, active turn, namespace and capability grants. Messages entered before the first acknowledgement wait for that turn's identity. The server stores steering durably and consumes it at model/tool boundaries, before proposed tools are dispatched or the final answer completes. An already executing tool finishes before the next model request receives the steering. A closed turn rejects late steering so the composer can recover the input.
POST /agent/sessions/:id/steer accepts turnId, messageId and message
(up to 8,000 characters). The authenticated conversation owner and active lease
are checked transactionally. messageId deduplicates retries within the turn;
there are at most 32 steering messages per turn. The chat SSE stream emits
{type:"steering", messageIds:[...]} when the messages enter model context.
Admission and the final queue check share a transaction, including across
server replicas. Capability and namespace changes require a new turn.
Memo tool writes commit after their complete arguments arrive; the built-in
agent does not stream partially generated text into the Memo. Read activity
publishes source-hash-bound ranges. dreamlake_notes_visit can publish intent
and an address/cursor together, pinned to the read's baseRevision; stale
locations are refused. dreamlake_notes_presence also reads source-bound human
selections and reports roster, selection and activity availability separately.
Empty activity arrays are not historical inactivity: the markers expire in
seconds. Use dreamlake_notes_diff from a retained revision for recent source
changes, without inferring human authorship. Selected editor text carried into
the composer is retained as bounded, untrusted page.quote context; its UTF-16
offsets must not be reused as API code-point ranges. See
agent presence.
The chat shows a thinking indicator and tool receipts, not provider reasoning
text.
For other resource operations the model uses this sequence:
- Call
dreamlake_resource_api_discoverwithfamily,searchormethod. Search matches every whitespace-separated keyword against the family, method, route and description; for example,artifacts POST. Results include operation IDs, methods, route templates, required scopes, availability and pagination (offset,limit,nextOffset). An unfiltered call also returns all registered resource families. - Call discovery again with one
operationID to obtain its exact path parameters, query, body and declared header schemas, plusreferencedSchemasfor any schema references.executionToolnames the correct gateway, or is null for an excluded operation.granteddescribes turn scopes only; it does not promise resource access or override an unavailable operation. - For project tree operations, use the discovered
dreamlake_resource_project_api_read,dreamlake_resource_project_api_writeordreamlake_resource_project_api_controltool and supplyprojectId. The server resolves the actual target and parent through the caller API, rejects a different project, checks the grant before dispatch and again before releasing read results. Project-root and access-management mutations additionally require an ADMIN grant. Project control requires bothresources:controlandprojects:writescopes. For other operations, calldreamlake_resource_api_read,dreamlake_resource_api_writeordreamlake_resource_api_controlwith that ID,parameters, optionalquery,bodyand conditional/idempotencyheaders. - Inspect the result. After an uncertain mutation, read the affected resource or its operation receipt before retrying. A pending command is not complete.
Read scope is available by default. Write and control scopes require the
client's explicit toolsWrite capability. Creation, archival, deletion,
sharing, grants and ownership transfer use the canonical resource route's
permissions and preconditions; enabling tools never supplies those permissions.
Destructive actions and outward access changes require the user's stated
intent. Resource discovery alone does not authorize an action.
Coverage and transport limits
Discovery enumerates each registered supported-method route under a recognized resource family. Every namespace resource family is discoverable; newly added families without an execution policy are returned as unavailable, instead of silently being enabled. Methods are GET, POST, PUT, PATCH and DELETE. The catalog is therefore the exact operation inventory for that running deployment; feature-disabled routes are absent rather than promised.
| Resource surface | Built-in interface |
|---|---|
| Agents/runnables, versions and execution bindings | Dedicated agent creation and discovered canonical operations |
| Projects, resource filings/bindrs, external mount grants and ownership operations | Discovered canonical operations; existing role checks and transfer review/acceptance still apply |
| Artifact, workflow, pipeline, environment, annotation, library and dataset metadata/lifecycle | Discovered canonical operations |
| Sources, connections, repositories and deletion-operation status | Discovered canonical JSON operations |
| Hosts, machines, jobs, runs, clusters, providers and infrastructure | Discovered read/control operations; the existing user-configured launch-server boundary remains authoritative |
| Memo metadata, creation, archive/delete and sharing | Discovered canonical operations or the existing Memo adapters |
| Memo ownership transfer | Dedicated preview, execute, recipient acceptance and status tools; legacy move remains separate |
| Memo body/sections/diff, duplicate and attached-file operations | Dedicated dreamlake_notes_* adapters preserve revisions, read coverage and recovery; discovery returns the adapter guidance |
| Project files/folders/tree nodes | dreamlake_resource_project_api_read / dreamlake_resource_project_api_write / dreamlake_resource_project_api_control support JSON tree operations with an explicit project grant and caller ACL; binary content uses the existing transport |
| Sessions and commands | Existing dreamlake_session_* / dreamlake_sessions_* adapters preserve durable command identity and bounded transcript reads |
| Memory | Dedicated memory adapters retain per-operation explicit-intent gates |
| Task creation, updates, moves, deletion/restoration, progress events and Note links | Project-granted resource gateway with canonical body schemas and revision checks; task progress events are bounded JSON |
| Skills, activity, search, social, billing and namespace metadata | Discovered canonical operations where the registered route has a JSON contract |
| Binary upload/download, streaming watch/events, interactive terminals, wildcard proxy routes | Discoverable with CLI/SDK workflow guidance; no raw binary or live-stream transport in model tools |
| Authentication, credentials, OAuth callbacks, Vault, service-account identity, daemon/internal APIs and recursive agent turns | Not executable through the resource gateway |
The raw gateway accepts no caller-selected URL, host, bearer, attribution or
arbitrary request header. Path parameters cannot contain separators or encoded
traversal. Array query parameters are sent as repeated keys. Bodies are limited to 64 KiB and validated against registered route
schemas before dispatch. Routes without a body or query schema cannot accept
that payload through this gateway. Only if-match, if-none-match,
idempotency-key and x-idempotency-key headers can be supplied. Responses are
bounded by the existing harness; credential-shaped fields (including snake_case tokens and password hashes) and credential-bearing URLs are redacted. A
truncated response is not a complete resource export.
The API is invoked in process with the signed-in caller's bearer. Each tool call retains its normal receipt, lease fence and timeout. Mutation receipts store an input digest rather than the full body. No generic resource operation can increase the selected agent's tool allowlist.
Note ownership transfers
These adapters require a server version that includes them and an enabled
Note metadata-transfer backend. Check GET /agent/tools for registration;
the preview also checks the server's current transfer capabilities. A tool
appearing in source code does not establish deployment readiness.
Use this workflow when a Note changes owning namespace. Filing a Note in
another project or adding a Bindr is a different operation. The legacy
dreamlake_notes_move can still return NOTE_TRANSFER_UNAVAILABLE; repeating
that call does not activate the transfer backend.
| Tool | Inputs | Result and authority |
|---|---|---|
dreamlake_notes_transfer_preview | note, source, destination | Read capability. Fetches the canonical plan and preview; returns ready, plan, preview and the exact review. Creates no transfer. |
dreamlake_notes_transfer_execute | review, confirm: true | Note write capability and source authority. Submits the reviewed request once. A pending operation still needs recipient acceptance. |
dreamlake_notes_transfer_accept | review, operationId, confirm: true | Note write capability and current destination acceptance authority. Accepts a matching pending operation; returns an already completed operation without another write. |
dreamlake_notes_transfer_status | note, namespace, operationId | Read capability in the source or destination namespace. Reads one operation without polling or changing it. |
For example, preview with:
Copy the returned review unchanged into execute. It includes the source and
destination slugs, resource ID, expected owner/version, destination namespace
ID, singleton manifest, preview hash and stable idempotency key. Do not build
this object from guessed IDs or generate a replacement key after a failure.
The supported policy is explicit: private visibility, preserved existing
access and preserved external filings, with no hand-selected retained grants.
Inspect the preview's blockers and filing counts. ready requires an executable
plan, no blockers and no detached filings. Other access-policy choices require
the ownership interface; the agent does not discard grants to make a move work.
Execute and acceptance are separate actions under the user's intent. confirm
is a tool argument acknowledging the reviewed request, not an authorization
grant. Only moved: true with a completed operation and ownerCommitted: true
establishes completion. Pending, rejected, expired, cancelled or recovery states
must be reported as such.
If submission or acceptance loses its response, preserve the review and read status with the known operation ID. If the ID is unknown, inspect outgoing ownership transfers through discovery to locate the request before considering an identical idempotent resend. Never automatically retry a POST, copy Note content as a fallback, or obtain a fresh plan/key to conceal uncertainty. Status remains available when the metadata adapter is disabled; execution and acceptance refuse that disabled capability.
Folders and tasks
Folder creation already uses the project gateway. Discover family: "nodes"
with method: "POST", inspect the selected /nodes schema, then call
dreamlake_resource_project_api_write with the granted projectId and:
Omit parentId for the project root. If supplied, it must identify an existing
folder or episode in the same granted project. The project node ID is not a
folder parent. Both caller permission and the service-account project grant
are required; destination and grant checks also protect rename/delete operations.
Find Task operations with search: "tasks", because their routes are nested
under the projects family. Creation, update, move, delete, restore, progress
events and Note links expose their canonical JSON body schemas. Use the
operation's project gateway and exact schema, including required revisions.
Read the current Task before an update; a stale revision requires a new read.
Task events are paginated JSON records. Note SSE events and other live streams
remain excluded from the generic gateway.
Other recent resource capabilities
These features already use canonical registered operations; they do not need duplicate dedicated tools. Inspect the schema in the running deployment first.
| Request | Discover and use |
|---|---|
| Share only an artifact's most recent version | Find the artifact catalog POST operation and set shareLatestOnly: true. Add share: true only when the user also requested issuing a share link. This does not upload a new artifact version. |
| Rename an annotation | Find the annotation PATCH operation and set title; unchanged visibility should be omitted. Annotation share operations remain separate. |
| Add a resource to a Bindr in another project | Discover Bindr membership operations and use the exact resource and Bindr identifiers. An association does not transfer resource ownership or imply formal project filing. Canonical namespace and access checks still apply. |
| Create an agent with an instruction Note and skill folders | Use dreamlake_agents_create as documented above. A definition is not a running session. |
Host inventory and partial search
dreamlake_hosts_list accepts prefix, search, page, pageSize,
offsetWithinPage (default 0) and archived. prefix filters the canonical catalog. search performs a literal,
case-insensitive match within one returned page, over names, IDs, verified
hostnames and observed IP addresses. Continue with page: nextPage and
offsetWithinPage: nextOffset, preserving all other inputs, even after zero
matches. A byte-limited result can continue within the same catalog page;
nextOffset returns to 0 for the next page. Both fields are null when exhausted.
total is the catalog count, not the number of search matches.
Both list and dreamlake_host_get return allowlisted catalog and enrollment
metadata, including verified hostname, network observations and system details.
Each host returns at most 20 enrollments, bounded further to 24 KiB, with at
most eight addresses per enrollment. enrollmentsTruncated and
network.addressesTruncated identify omissions; inventoryOmitted summarizes
them for the scanned rows. searchIncomplete signals a continuation or omitted inventory.
This is a bounded lookup, not an exhaustive network search.
Unknown/unverified inventory remains null. Network observations carry
observedAt and freshness (fresh for at most 60 seconds, otherwise stale).
IPs are validated observed addresses, not inferred from hostname spelling.
Online or fresh inventory does not prove SSH or workload readiness.
Host connection grants
dreamlake_host_access_grants, dreamlake_host_access_grant and
dreamlake_host_access_revoke manage who may connect to a host you
own, using the same owner-only grant
as Compute. Listing needs only the default host read scope and returns
grants (people) and teamGrants (organization teams). Granting and
revoking need Full access for the message, and run only when you name the
person or team and the machine. dreamlake_host_access_grant takes exactly one
of grantee (a username) or team (a team slug). A grant takes an exact hostId and enrollmentId, so
the agent asks which Unix account when a host has several, and says that the
member will act as that account; for a team, that this applies to every
current direct member and to anyone added later (parent teams are not
included). The generic resource API tools refuse the
access-grants routes and point to these tools. Background (durable) turns
cannot use them.
An unconfirmed grant or revoke is reported as uncertain, and the agent lists
grants before doing anything else rather than repeating the call. A revoke
reports closedConnections, stillAuthorizedConnections (kept because the
same person holds another current grant to that enrollment) and
unconfirmedConnections; while
closeConfirmed is false, the agent reports the connections as possibly open
until unconfirmedUntil, not as closed.
The agent files a host you own in a Project of the same namespace with
dreamlake_resource_project_api_write (resourceType: "host"), which needs an
explicit service-account grant on that Project. Filing is placement only and
gives Project members no host access; see
Hosts in Projects.
dreamlake_host_move_preview reports projectPlacements when the host is
filed; applying the move unfiles it from that many Projects without deleting
the host, and the agent says so before applying.
Connections and credential entry
Use the credential-entry tools below when the deployed assistant offers them. If they are not offered, create or reconnect through the signed-in Connections page instead; this reference does not establish their availability in every deployment.
Connection reads — GET /namespaces/:ns/connection-connectors, the list,
detail, Check and affected Sources — and credential-free create (an auth kind
whose mode is none) are discovered canonical operations, available to the
namespace's credential managers. The gateway refuses any tool call that carries
a credential, so a Connection that needs a secret is created or reconnected by
browser credential entry:
dreamlake_connection_entry_begin(resources:write) starts an entry in the turn's namespace for one connector andfieldsauth kind (create), or for one Connection at its current settings revision (reconnect). It returns an operation id and a link to the Connections page; the label is only a suggestion the user may edit.- The user opens the link, signed in, and enters the secret in the existing form. The entry is bound to that user and namespace, single use, and expires after 30 minutes; the connector, auth kind, target and revision cannot be changed there.
dreamlake_connection_entry_status(resources:read) returnspending,succeeded(with the Connection id and masked metadata),cancelledorexpired. It works after a reload or a later turn.dreamlake_connection_entry_cancel(resources:write) closes a pending entry.
Neither the arguments, the results nor the receipts of these tools contain a credential. The entry routes are not reachable through the generic gateway. Background and delegated runs, and service accounts, cannot manage Connections, and Connections cannot be granted to an agent service account.
Recovering from tool errors
Canonical schema failures now return a bounded validation object to the
model: operation ID, input part, schema path, keyword and, where applicable,
the missing schema property or numeric limit. Values, unknown property names,
raw API errors and document bodies are omitted. These details are not added
to browser tool-event telemetry.
| Error | Meaning and next step |
|---|---|
agent_resource_body_invalid, agent_resource_query_invalid | No API request dispatched. Rediscover the exact operation, resolve referencedSchemas and correct the indicated constraint. Do not repeat identical arguments. |
agent_resource_tool_mismatch | The operation uses another gateway, such as write instead of read or a project-granted gateway. Inspect executionTool; use it only if offered this turn. |
agent_resource_schema_missing | A supplied body/query has no declared canonical schema. Use the documented dedicated adapter or report the specific capability gap. |
agent_resource_operation_unavailable | Follow dedicatedTools and guidance; do not bypass an excluded transport or authorization boundary. |
agent_tool_scope_not_granted | The current turn lacks the capability. This does not establish whether the underlying API exists. |
NOTE_TRANSFER_UNAVAILABLE | Use the reviewed transfer workflow when available; do not repeatedly call legacy move or remove access grants. |
note_transfer_outcome_unknown | The transfer may have changed state. Preserve the original review/key and inspect status before any further mutation. |
When reporting an error, retain its exact code, tool, time and available receipt/request IDs. A 404 alone does not distinguish an incorrect identifier, wrong namespace, unavailable route or denied visibility. Inspect authorized resource discovery before attributing it to a missing tool.