Self-awareness — Wisp's actual capabilities
Use only tools advertised in the current conversation. Wisp exposes agent and
desktop capabilities as explicit tools; do not assume that an SDK documented by
another application also exists here. Some tools are conditional on the desktop
session, project settings, execution context, or capability grants. If a tool is
not advertised, treat it as unavailable.
Python and R boundary
Use python for persistent Python analysis and r for persistent R analysis.
Their variables and imports persist per conversation and execution context
within the project/scope; parallel conversations do not share interpreter state.
In the desktop, an omitted context_id uses the conversation's selected default
context (falling back to local). Pass local, ssh:<alias>, or wsl:<distro>
explicitly when needed. The CLI's language runtimes are local.
The Python worker initializes an ordinary namespace with common standard-library
modules and any available convenience packages. It does not inject a Wisp
control-plane object. Code executed with python therefore cannot directly call
the agent model, spawn Agents, submit or monitor Runs, inspect Wisp credentials,
or query internal project/session metadata. Leave the Python cell and call the
corresponding Wisp tool instead.
Capability reference
| Need |
Wisp interface |
Availability and boundary |
| Read, create, or patch project files |
read, write, edit |
Operate on normal filesystem paths within the granted workspace. |
| Find files or text |
search, grep |
Use before broad manual inspection. |
| Run a short command |
shell |
Use for bounded foreground commands, not as a long-running job manager. |
| Interactive Python or R analysis |
python, r |
Persistent per conversation and execution context; no injected control-plane SDK. |
| Inspect a local image |
view_image |
Explicit tool call for a supported local image; this is not a Python method. |
| Track a multi-step plan |
update_plan |
Update task progress when a plan materially helps. |
| Present the completed result |
attempt_completion |
Wisp's normal completion path; there is no separate structured-output submission SDK. |
| Audit configured workflow guidance |
list_skill_catalog |
Page through discovered/effective records and use its explicit counts. |
| Discover and load workflow guidance |
search_skills, use_skill |
Search by task/domain, then load the exact returned skill name. |
| Search confirmed project notes |
search_memory |
Available only when project memory is enabled. New notes are proposed after a completed turn and require confirmation in the Wisp UI; there is no direct memory-write tool. |
| Delegate multi-file codebase reading |
explore |
Read-only sub-Agent with its own context and read/grep/search access. |
| Delegate general bounded tasks |
delegate_tasks |
Desktop-only and capability-gated. Use it only when its schema is advertised; it is not callable from Python. |
| Read a truncated delegated result |
get_delegated_result |
Desktop-only and available with delegation. Use only when the compact result lacks necessary detail. |
| Submit long-running work |
run_in_context |
Persist a Run in local, ssh:<alias>, or wsl:<distro>. Prefer this over extending shell timeouts. |
| Read one Run snapshot |
get_run |
Call once for an immediate status check; never poll it in a loop. |
| Wait for a Run |
monitor_run |
Call with the Run id to wait without polling get_run. If wait_interrupted is true, respond, then call monitor_run again; do not resubmit. |
| Cancel a Run |
cancel_run |
Request cancellation through the persisted Run lifecycle. |
| Record project research objects |
research_graph |
Desktop-only. Record data assets, papers, or decisions and link existing graph nodes; it is not a generic artifact browser. |
| Read or change app preferences, or show disk storage |
configure |
Desktop-only. get / set cover allowlisted appearance and general settings (font size, theme, custom_css, locale, compaction). storage reports this project's workspace plus app-data usage in the conversation. Secrets, API keys, model profiles, workspace directory, and proxy are not writable. For a restyle, load custom-theme then set custom_css. |
| Create or update a specialist |
save_specialist |
Desktop-only. Omit id to create; pass id from configure get specialists to update. Builtin instruction text stays pinned. Deletion remains in Settings. |
| Make an extra model call from Python |
Not available |
Continue through the normal agent turn. For bounded delegated work, use explore or advertised delegate_tasks. |
| Resolve artifact ids to paths, list a generic artifact store, or inspect lineage |
Not available |
Use ordinary project paths plus read/search/grep. Do not invent artifact ids, version ids, or lineage records. Run output registration is limited to the explicit output_specs contract of run_in_context. |
| Read credentials from Python or an agent tool |
Not available |
Wisp keeps secrets outside SQLite in its keyring path; no credential accessor is exposed to the agent. |
| Query frames, token/cost accounting, tool-call history, or the internal metadata DB |
Not available |
Use only conversation context and tool results already provided. Do not claim access to hidden session tables or telemetry. |
Choosing the right execution path
shell executes short commands in fresh processes; python and r retain
interpreter state across calls. Choose based on the user's workflow, state
reuse, script requirements, and task lifecycle. Use the selected environment
and keep reproducible source in project files with either method.- Persistent runtimes support interactive analysis and reuse of loaded objects.
Execute saved analysis with
script_path and required_objects when it
consumes existing bindings. Do not move it to a fresh process merely because
it takes time. Match execution to the script's process requirements.
- Use
run_in_context for standalone background, remote, or long-running work. Use
monitor_run when the result is needed in the current task (again after
wait_interrupted; do not resubmit), or return the Run id for fire-and-forget
work.
- Use
explore when codebase understanding requires more than a couple of
reads. Use delegate_tasks only when desktop delegation is currently
advertised and the work benefits from independent or parallel Agents.
- Use ordinary project files for inputs and outputs. Never fabricate an
artifact registry, lineage API, credential API, session database, or
Python-side bridge for a capability that is not present.
For SSH-direct details, load remote-compute-ssh; its Run workflow and current
limitations are the authoritative Wisp contract.
1---2name: self-awareness3description: Wisp-science's actual agent tool surface and runtime boundaries. Load this when deciding which Wisp tool can perform a task, checking whether Python can reach agent or desktop capabilities, choosing between interactive analysis and persisted Runs, or answering questions about delegation, images, skills, memory, artifacts, lineage, credentials, session history, and other self-introspection capabilities.4license: Apache-2.05---6
7# Self-awareness — Wisp's actual capabilities
8
9Use only tools advertised in the current conversation. Wisp exposes agent and
10desktop capabilities as explicit tools; do not assume that an SDK documented by
11another application also exists here. Some tools are conditional on the desktop
12session, project settings, execution context, or capability grants. If a tool is
13not advertised, treat it as unavailable.
14
15## Python and R boundary
16
17Use `python` for persistent Python analysis and `r` for persistent R analysis.
18Their variables and imports persist per conversation and execution context
19within the project/scope; parallel conversations do not share interpreter state.
20In the desktop, an omitted `context_id` uses the conversation's selected default
21context (falling back to local). Pass `local`, `ssh:<alias>`, or `wsl:<distro>`
22explicitly when needed. The CLI's language runtimes are local.
23
24The Python worker initializes an ordinary namespace with common standard-library
25modules and any available convenience packages. It does **not** inject a Wisp
26control-plane object. Code executed with `python` therefore cannot directly call
27the agent model, spawn Agents, submit or monitor Runs, inspect Wisp credentials,
28or query internal project/session metadata. Leave the Python cell and call the
29corresponding Wisp tool instead.
30
31## Capability reference
32
33| Need | Wisp interface | Availability and boundary |
34|---|---|---|
35| Read, create, or patch project files | `read`, `write`, `edit` | Operate on normal filesystem paths within the granted workspace. |
36| Find files or text | `search`, `grep` | Use before broad manual inspection. |
37| Run a short command | `shell` | Use for bounded foreground commands, not as a long-running job manager. |
38| Interactive Python or R analysis | `python`, `r` | Persistent per conversation and execution context; no injected control-plane SDK. |
39| Inspect a local image | `view_image` | Explicit tool call for a supported local image; this is not a Python method. |
40| Track a multi-step plan | `update_plan` | Update task progress when a plan materially helps. |
41| Present the completed result | `attempt_completion` | Wisp's normal completion path; there is no separate structured-output submission SDK. |
42| Audit configured workflow guidance | `list_skill_catalog` | Page through discovered/effective records and use its explicit counts. |
43| Discover and load workflow guidance | `search_skills`, `use_skill` | Search by task/domain, then load the exact returned skill name. |
44| Search confirmed project notes | `search_memory` | Available only when project memory is enabled. New notes are proposed after a completed turn and require confirmation in the Wisp UI; there is no direct memory-write tool. |
45| Delegate multi-file codebase reading | `explore` | Read-only sub-Agent with its own context and `read`/`grep`/`search` access. |
46| Delegate general bounded tasks | `delegate_tasks` | Desktop-only and capability-gated. Use it only when its schema is advertised; it is not callable from Python. |
47| Read a truncated delegated result | `get_delegated_result` | Desktop-only and available with delegation. Use only when the compact result lacks necessary detail. |
48| Submit long-running work | `run_in_context` | Persist a Run in `local`, `ssh:<alias>`, or `wsl:<distro>`. Prefer this over extending `shell` timeouts. |
49| Read one Run snapshot | `get_run` | Call once for an immediate status check; never poll it in a loop. |
50| Wait for a Run | `monitor_run` | Call with the Run id to wait without polling `get_run`. If `wait_interrupted` is true, respond, then call `monitor_run` again; do not resubmit. |
51| Cancel a Run | `cancel_run` | Request cancellation through the persisted Run lifecycle. |
52| Record project research objects | `research_graph` | Desktop-only. Record data assets, papers, or decisions and link existing graph nodes; it is not a generic artifact browser. |
53| Read or change app preferences, or show disk storage | `configure` | Desktop-only. `get` / `set` cover allowlisted appearance and general settings (font size, theme, `custom_css`, locale, compaction). `storage` reports this project's workspace plus app-data usage in the conversation. Secrets, API keys, model profiles, workspace directory, and proxy are not writable. For a restyle, load `custom-theme` then set `custom_css`. |
54| Create or update a specialist | `save_specialist` | Desktop-only. Omit `id` to create; pass `id` from `configure` get `specialists` to update. Builtin instruction text stays pinned. Deletion remains in Settings. |
55| Make an extra model call from Python | Not available | Continue through the normal agent turn. For bounded delegated work, use `explore` or advertised `delegate_tasks`. |
56| Resolve artifact ids to paths, list a generic artifact store, or inspect lineage | Not available | Use ordinary project paths plus `read`/`search`/`grep`. Do not invent artifact ids, version ids, or lineage records. Run output registration is limited to the explicit `output_specs` contract of `run_in_context`. |
57| Read credentials from Python or an agent tool | Not available | Wisp keeps secrets outside SQLite in its keyring path; no credential accessor is exposed to the agent. |
58| Query frames, token/cost accounting, tool-call history, or the internal metadata DB | Not available | Use only conversation context and tool results already provided. Do not claim access to hidden session tables or telemetry. |
59
60## Choosing the right execution path
61
621. `shell` executes short commands in fresh processes; `python` and `r` retain
63 interpreter state across calls. Choose based on the user's workflow, state
64 reuse, script requirements, and task lifecycle. Use the selected environment
65 and keep reproducible source in project files with either method.
662. Persistent runtimes support interactive analysis and reuse of loaded objects.
67 Execute saved analysis with `script_path` and `required_objects` when it
68 consumes existing bindings. Do not move it to a fresh process merely because
69 it takes time. Match execution to the script's process requirements.
703. Use `run_in_context` for standalone background, remote, or long-running work. Use
71 `monitor_run` when the result is needed in the current task (again after
72 `wait_interrupted`; do not resubmit), or return the Run id for fire-and-forget
73 work.
744. Use `explore` when codebase understanding requires more than a couple of
75 reads. Use `delegate_tasks` only when desktop delegation is currently
76 advertised and the work benefits from independent or parallel Agents.
775. Use ordinary project files for inputs and outputs. Never fabricate an
78 artifact registry, lineage API, credential API, session database, or
79 Python-side bridge for a capability that is not present.
80
81For SSH-direct details, load `remote-compute-ssh`; its Run workflow and current
82limitations are the authoritative Wisp contract.
xuzhougeng