/self-awareness

name: self-awareness
description: Inspect Open-Science's JavaScript control REPL, discover managed Project files, Sessions, and Agent Frames, and safely feature-gate host.* calls with host.capabilities(). Use when an Agent needs to discover available host APIs, locate an Artifact or Upload Version, diagnose a Session, or read a Frame transcript in the current Project.

Self-awareness

Use `repl_execute` for every `host.*` call. The `host` object exists only in the persistent JavaScript control REPL; Python and R data kernels do not receive it.

Inspect available capabilities

const caps = await host.capabilities()

The current project-native result contains 20 known boolean keys:

• `mcp` gates connector calls through `host.mcp(server, method, args?)`.
• `compute` gates the `host.compute` namespace.
• `agents` gates the `host.agents` namespace.
• `skills` gates the `host.skills` namespace.
• `artifacts` gates managed-file discovery through `host.artifacts(options?)` and exact path

resolution through `host.artifactPath(versionId)`.

• `lineage` gates the read-only `host.lineage` namespace.
• `frames` gates the read-only `host.frames` namespace.
• `sessions` gates Main-only, read-only Session diagnostics through `host.sessions.list(options?)`

and exact lookup through `host.sessions.inspect(sessionId)` in the current Project.

• `llm` gates one-shot, tool-less inference through `host.llm(request, options?)`.
• `currentModel` gates exact current-model lookup through `host.currentModel()`. It returns the

calling Session's exact current model id and fails when the live backend cannot establish one.

• `listModels` gates configured Host LLM model discovery through `host.listModels()`. It returns the

frozen, stable-sorted configured model ids for the current Host LLM Provider and framework. It never refreshes over the network or merges ids across Providers.

• `viewImage` gates transient image attachment through `host.viewImage(source, options?)`. Sources

may be an Artifact or Upload Version in the current Project, or a path relative to the current execution workspace. For a generated file, pass the same relative path used to save it.

• `delegate`, `children`, `collect`, `stopChild`, and `resolveMessage` are Main/root-only delegated

work operations.

• `sendFrameMessage` and `messageReceipt` are available to Main/root and Delegate agents when their

trusted route is provisioned.

• `submitOutput` is available only to an authenticated Delegate Attempt with an admitted output

schema.

Newer runtimes may return additive boolean keys. Do not assume their meaning until their matching Skill documents them. Older runtimes can omit known keys.

Interpret every key narrowly:

• `true` means the current session capability authorizes the namespace and the application has its

handler configured. It does not mean a resource exists, approval is unnecessary, or a call will succeed.

• `false` means the capability name is known but unavailable to this caller.
• A missing key means this runtime does not know that capability. Test with `=== true`.

const caps = await host.capabilities()
if (caps.compute === true) {
  const availableHosts = await host.compute.listHosts()
}

if (caps.llm === true) {
  const result = await host.llm('Summarize the current findings.')
}

if (caps.currentModel === true) {
  const sessionModel = await host.currentModel()
}

if (caps.listModels === true) {
  const hostLlmModels = await host.listModels()
}

if (caps.sessions === true) {
  const recentSessions = await host.sessions.list({ limit: 20 })
}

if (caps.viewImage === true) {
  await host.viewImage({ path: 'results/plot.png' }, { maxSize: 1200 })
}

if (caps.sendFrameMessage === true) {
  await host.sendFrameMessage('parent', 'The analysis is ready.')
}

Do not infer capabilities by reflecting over `host`, and do not treat this result as a resource, credential, permission, or readiness inventory. Call it again when current availability matters; each call returns a fresh frozen projection.

`host.help()` documents registered topics only. A `not_found` result identifies missing Help documentation: `not_found` does not override `host.capabilities()` or prove that a method is absent.

Discover managed Project files

When `caps.artifacts === true`, use `await host.artifacts(options)` to list generated Artifacts and user Uploads across the current Project. Optional camelCase fields are `versionId`, `frameId`, `filename`, `exact`, `search`, `contentType`, `after`, `before`, `cursor`, and `limit` (default 20, maximum 100). `versionId` is exclusive; `exact` requires `filename`; `search` and `filename` cannot be combined. `contentType` accepts an exact MIME type or a top-level prefix such as `text/`. Bare dates are UTC midnight, `after` is inclusive, and `before` is exclusive.

const page = await host.artifacts({ search: 'report', limit: 20 })
const localPath = page.artifacts[0]
  ? await host.artifactPath(page.artifacts[0].latestVersionId)
  : undefined

`frameId` matches only the exact producer Frame of a generated Artifact's latest Version. It does not expand to a root's descendants or the whole Session, and Uploads without trusted Frame provenance are excluded while this filter is present. There is no Session or Project override and no all-Projects scope. `count` is the total number of matches before cursor pagination; the current page size is `artifacts.length`. `nextCursor` is absent on the last page.

{
  count, projectId, truncated, nextCursor,
  artifacts: [{
    id, filename, contentType, sizeBytes, latestVersionId, checksum,
    projectId, sessionId, rootFrameId, agentFrameId, isUserUpload,
    createdAt, latestVersionCreatedAt
  }]
}

Result and Artifact fields use camelCase. `contentType`, `checksum`, `rootFrameId`, and `agentFrameId` are always present and may be `null`. Results contain metadata and immutable Version identit