blockether.vis.extension

Operations every injected or outside vis host must implement.

Create, find and read Vis sessions from an extension, as vis.sessions.

Each method returns blockether.vis.engine.Session handles that use the host. The host records this extension as the origin of each session that it creates. An extension can change only its bound session, its child sessions and its own sessions.

Create an independent session, run one turn in it and return the result.

The arguments are those of blockether.vis.engine.Agent.run. provider and model pin the model of the new session. Without response_model, the result is the turn record; check its status. Only an extension callback can call it.

Plain Activity text, never a model message or a question.

Heading for a section of this invocation's current content.

Markdown content for this invocation.

Code with an optional language hint.

A diff, not engine-observed file-change evidence.

A rectangular table. Input lists are snapshotted as tuples.

paths is optional and, when given, holds one workspace path per row so clients can open that row's file. Use an empty string for a row without one.

Reference an existing attachment, never an external media URL.

Display an existing image attachment.

Display an existing video attachment.

Display an existing audio attachment.

Progress with paired value/total, or an indeterminate indicator when omitted.

One output line of an ActivityTerminal. Vis shows "stderr" lines as errors.

A command and its output, shown like a terminal.

command holds one or more stages. Start each later stage with its operator, for example ("cd app", "&& npm test", "| tail -8"). Vis highlights the operators. lines holds the output in order; a plain string is a stdout line. Keep the end of long output and count the dropped lines in omitted_lines. Remove ANSI escape codes first. exit is the exit code of a finished command.

A visible headline and one-line summary.

Only the content waits behind disclosure.

summary_format="markdown" opts into inline Markdown with HTTP(S) links. Unmarked or "inline" summaries are literal text. The 512-byte, one-line limit includes Markdown source. Images, HTML and block layout are not shown.

One atomic symbol presentation, optionally linked to a persistent handle.

Use the same non-secret handle_id for later receipts of one operation in this extension and Python form. Vis shows one current outcome, and it keeps distinct details, errors and every invocation in history. Omit it for independent calls. A handle is not a label, tool argument or return value.

Set verdict when the call finished but reports on checks: "failed" for failing tests or lint findings, "passed" when every check passed. Vis pins a failed verdict in the settled turn's digest until a later run of the same tool passes.

outcome is one short result line. Vis shows it after an arrow on the closed row, for example the last line of command output. aside is short muted context at the right edge of the row, for example a directory or "exit 1".

Human-facing symbol presentation. The engine owns identity, timing and outcome.

Declare Activity on every exported callable, including each object method. Write understandable English for people, not Python identifiers or object reprs. Labels and headlines use sentence case ("Read file", "Run tests") and keep proper names and acronyms. Summaries explain the target, useful counts or outcome. Use render or publish_activity for selected content. Return values stay independent.

show_start=False makes a fast operation end-only: no running row or start callback. Use it for quick reads, patches and local lookups. Keep show_start=True for work people wait for, such as tests, network requests or transfers. Internal start/end tracking still preserves ordering, timing, errors and cancellation. Published content is kept but stays hidden until an end-only invocation settles.

The final presentation must stand alone: name the target and outcome, including empty results or failures reported as return values. A normally returned failed workflow is still a failed workflow. "Completed" alone is not enough. Label partial lists and excerpts, and keep useful counts, errors and changes.

render is an optional synchronous callback. It receives phase, args, kwargs, result and error as keyword arguments. It returns an ActivityPresentation, or None to keep the current presentation. It runs on success and failure, and on start only when show_start=True. Use publish_activity for intermediate stages of long-running tools. Rendering failures never change returns or errors.

Arguments:

• presenter: Presentation category. Leave "generic" for ordinary tools.
• label: Optional nonblank, single-line label of at most 96 characters.
• render: Synchronous callback accepting phase, args, kwargs, result and error keyword arguments. Return an ActivityPresentation or None.
• show_start: Whether readers see a running row before the call settles.

Raises:

• TypeError: show_start is not boolean or render is not synchronous/callable.
• ValueError: The presenter is unknown or the label is invalid.

Replace headline, summary, content and sections without authoring lifecycle.

Headline and summary stay visible when collapsed. Content uses typed text, Markdown, table, code, diff, attachment and progress blocks. Sections group multiple results with one blank line between them. To clear content, publish the same headline/summary with empty content. None from render keeps the last snapshot. Returns False outside an invocation or when publication is rejected.

Declare a boolean, choice or text setting shared by the app and TUI.

scopes allows any non-empty combination of global, project, group and session. Omitting it uses the contract's global-only default. A project extension exists only in its project, so there global means the whole project. The setting shows in its extension's own settings section. value() reads the current callback's response snapshot. Its type follows default: bool for a boolean setting, str for a choice setting and for a text setting. Outside Vis, it returns the declared default. A string setting holds one line of text. is_secret=True makes it write-only: Settings show only whether a value is saved. A secret needs the default "" and only the global scope. Its value stays on this machine and out of trajectories. Read a secret while Vis calls its own extension, for example in a tool. Elsewhere, value() can return the default. parent names another setting of the same section. Settings shows this setting under that setting. Settings can nest at any depth. on_change(old, new, scope) runs once after a person changes the setting in the app or TUI and its effective value changes. scope is global, project, group or session. Vis keeps the saved value if the hook raises, and shows the error.

Group tools and host capabilities in one immutable declaration.

Arguments:

• name: Human-readable, nonblank extension name.
• description: Nonblank description of what the extension does.
• alias: Python namespace for exported symbols. Required with symbols.
• symbols: Symbol declarations for functions or object namespaces.
• version: Optional extension version string.
• kind: Optional extension kind understood by the host.
• activation: Optional host activation callback.
• prompt: Instructions as text or a host callback.
• slash_commands: SlashCommand declarations.
• keybindings: Keybinding declarations: TUI keys after C-x.
• op_hooks: OpHook declarations for host lifecycle operations.
• ctx: Optional host context callback.
• providers: Provider declarations.
• network_filters: NetworkFilter declarations.
• settings: Host-owned Setting declarations with explicit allowed scopes.
• env: Environment variable names resolved at host registration.
• grants: Grant declarations: toolchain paths for this extension's jailed_shell children.

Collection inputs are copied into tuples. Constructing an Extension is pure: it does not run callbacks or register anything. In an application, pass it to blockether.vis.engine.Agent or its register_extension method. In an installed extension entrypoint, call this module's register_extension once instead. The application callback bridge rejects host-only fields before connecting.

Raises:

• ValueError: A required name, alias, callback or environment name is invalid.
• TypeError: A field has the wrong type or a collection contains something other than its corresponding SDK declaration.

Register one typed declaration and resolve its declared environment in this context.

Construction is pure, and registration is the only host boundary. A failure before completion leaves the context unregistered. No constructor registers itself.

Declare a dataclass's public list or tuple field as its sandbox sequence.

Apply this outside @dataclass. The returned class is unchanged except for metadata: original methods are neither called nor transported. Each subclass must opt in separately. Values are checked when an extension returns them. The backing field must hold a built-in list or tuple, not a lazy iterable.

Sandbox records iterate over the received field and support length, truth testing, integer indices and slices. String keys still read named fields. Only the received items are exposed, and iteration never fetches another page.

Describe a public method on an object exported through Symbol.

Arguments:

• fn: Method to annotate. Omit it to use @method(...).
• tag: What the method does, as Activity reports it. "observation" reads, "mutation" changes local state and "verification" checks work (tests, lint, CI status). "external" reaches people or systems beyond the session (messages, publications, remote hosts).
• is_hidden: Hide the method from discovery without removing the callable.
• activity: This method's human-facing presentation. Declare it on each exported method, not on the containing object namespace.

Returns:

The original method, or a decorator returning it. Calling your method directly still uses normal Python behavior. This decorator adds metadata.

Raises:

• ValueError: The tag is unsupported or the decorated value is not callable.
• TypeError: The Activity declaration has the wrong type.

from blockether.vis.extension import Activity, Symbol, method


class Greeter:
    @method(activity=Activity(label="Greet person", show_start=False))
    def hello(self, name: str) -> str:
        "Return a greeting for the named person."
        return f"Hello, {name}!"


greeter = Greeter()
tool = Symbol(greeter, name="greeter")
assert greeter.hello("Ada") == "Hello, Ada!"
assert tool.contract["members"][0]["name"] == "greeter.hello"

Expose a function or an object's public methods as typed tools.

Arguments:

• fn: Function, or an object whose public methods form a namespace.
• name: Override the function name. Required for objects, and must then be a public Python identifier.
• tag: Default operation classification, one of the method tags.
• is_hidden: Hide the symbol from discovery without removing the callable.
• activity: Human-facing presentation for a function. Declare one on every exported callable. For an object, leave this unset and put an Activity on every exported method instead.

Construction validates the declaration and derives its contract without calling the function or starting Vis. Function docstrings and type annotations become tool documentation, not runtime argument validation. Export narrow objects: public methods and nested namespace objects are traversed, not just methods bearing the decorator.

Raises:

• ValueError: A callable lacks a docstring, or the name, operation tag, Activity placement or namespace is invalid, including cycles and repeated object references.
• TypeError: A declaration field has an unsupported type.

An inert Python type description. References bound recursive records.

A dataclass field. Default values and factories are never exported or run.

A callable parameter. default_source is inert source, or None when unavailable.

Typed view of one public callable's authoritative Symbol contract.

A public namespace and its callable descendants, with full dotted names.

Generated reference text, not captured CLI output or an operation result.

Read-only snapshot of public Symbols. Construction and lookup do no IO.

Pass the same symbols to Catalog and Extension. Rebuild after changing declarations. This is an adapter, not a registry, dispatcher or runtime type validator.

A user-facing slash command, not a model-facing tool.

A TUI key binding: C-x, a group key and this key run a command, a verb or a function.

Arguments:

• key: One printable ASCII character from ! to ~.
• command: A slash command line that starts with /. The TUI runs it as if the person typed it and pressed Enter. Give it with label.
• action: A built-in TUI verb id in kebab case, such as new-session. The verb moves to key.
• label: The key menu and palette label. Required with command and run.
• group: The C-x group of the key. A built-in group name, such as Session, places the key there, in any case. A command or run binding without a group uses Extensions (C-x e). Any other name makes a group of its own under C-x e, opened by the first free letter of the name. An action binding without a group stays in the group of its verb.
• run: A function that the gateway calls when the person presses the key. It adds no turn to the transcript. It receives a dict with key, group, channel, session_id, workspace_root and project_root. It returns None, a text, vis.ok(...) or vis.err(...), and the TUI shows the title. Call vis.notify(...) in it to tell every client of the session.

Give exactly one of command, action and run.

Raises:

• ValueError: A field breaks these rules.

An operation observer or a fail-closed gate. Never mix both kinds in one hook.

Request/response policy at the host's network-filter boundary.

Filesystem access that this extension's own jailed child processes need.

A toolchain often lives outside the workspace: a JDK, a package cache or a launcher. Declare each path once. The host checks every grant at registration. It adds the grant only to the jailed_shell children of this extension. The model's shell never receives it, and the jail deny rules still win.

Arguments:

• path: Absolute path, or a path that starts with ~.
• mode: "read" to read and run files, or "read_write" for a cache that the tool also writes.
• reason: Short text that tells people why the extension needs the path.

Raises:

• ValueError: The path or reason is blank, or the mode is unknown.

Endpoint defaults, not credentials. Opaque API payload keys remain unchanged.

extra carries additional router settings as JSON, never overriding named fields. Use enrich_models_fn for typed model metadata beyond default model names.

A usable credential. Tokens and headers are excluded from repr.

Return None instead when no credential is available.

Connection verdict, separate from usage limits. extra is display-only JSON metadata.

Model metadata returned by enrichment. extra keeps additional router fields.

is_tool_call and is_image_input are old names of is_tool_calls_supported and is_vision_supported. They still work. A new name wins over its old name.

The contract's calendar, rolling or lifetime window for one limit.

One usage row in contract form.

Finite measurements keep their original precision.

A limits failure, not an exception carrying a credential.

Usage snapshot. The host fills omitted provider_id and fetched_at_ms values.

Pure provider declaration. register_extension adapts its callbacks to the host.

Credential reads are passive, and only auth_fn may start a login. Callbacks are synchronous and may run without a session. Refresh accepts zero arguments or one rejected token (None if unknown), chosen without retrying callback errors. Enrichment and selection inputs remain JSON mappings owned by the router or config, not a second SDK schema for those domains. Callback outputs use typed records.

Refuse the call a before op hook is deciding.

The model reads reason as the tool failure. hint tells it what to do next; without one, the failure advises asking the user before a retry.

Return repaired source from a before hook, without writing or running it.

Only patch accepts this decision. Vis repairs python_execution blocks itself with parinferish. The host validates the request and reports the notes with the result. A patch still checks the complete original file before it writes the repaired text once.

Return the active session workspace as a path, including its current draft.

This is the primary working copy, not a language-specific project marker. Outside Vis, it is the process directory. A hosted call without a bound session fails instead of silently using the gateway process directory.

Return this extension's project root in the active session workspace.

The project root is the nearest directory above the extension entry that holds a .vis directory, mapped into the session working copy. For an extension in the workspace's own .vis/extensions, it is workspace_root(). Outside Vis, it is the process directory. A hosted call without a bound session fails, like workspace_root().

Return the files under workspace_root() that Git sees.

The list holds tracked files and untracked files that Git does not ignore. The host lists the working copy once and gives the same list to each extension that asks within a short time. Use it instead of a child process for each extension. The result is None when the workspace is not in a Git working tree. Outside Vis, it lists the process directory.

Return the Python environment that the session's project selects.

The value comes from python.environment in the merged configuration. shared means that project Python runs like vis-agent python --shared, with Vis shared packages and without the project's .venv. project, the default, means that the project's own environment applies. Outside Vis, the value is project.

Replace path with text in one atomic step, readable only by its owner.

A failure keeps the previous file. A symbolic link writes the file it names. Missing parent directories are created owner-only.

Store an artifact as a durable attachment of the running block, or open an app.

source is a path, bytes, a Matplotlib figure or a Pillow image. The engine stores the artifact with the python_execution block that called this tool, exactly like the sandbox attach verb. A second attachment under the same filename is the next version of that artifact. audience is both, user or model; a PDF or HTML document is for the user only.

Returns the descriptor dict: id, filename, version, media_type, kind, size and audience. Every read function takes it as its target.

An app declaration from vis.ui.app(...) opens an app and answers its LiveAttachment handle. The app row from list_attachments() answers a handle for that app again. An app takes only on_event(event), which then runs for each human change, submit, activate or shortcut, as with vis.live.

List the artifact descriptors of this session, oldest first.

The list includes the artifacts that the running block attached. With name, it lists the versions of that one artifact.

Return the descriptor of one artifact, without its bytes.

target is a filename, an id or a descriptor. A filename means the latest version, unless you give version. A negative version counts back.

Return the bytes of one artifact. target works as in get_attachment.

Show a stored image to the model for the next request only.

target works as in get_attachment. Returns the id, filename, media_type and size of the queued image.

Read one whole session, exactly as the sandbox read_session does.

Without target, it reads the session that runs the extension. target takes a bare id, an unambiguous prefix or the copied vis_session_id#<uuid> marker. The introspection toggle does not apply, because an extension is trusted code.

Returns the same string-keyed dict: session, current_turn, failures, diagnosis, session_forks, turn_retries, usage and transcript.

List sessions newest first, exactly as the sandbox list_sessions does.

With search, it runs the session search of the TUI and the Companion app. The rows come in rank order: title, request, reply, then thinking, newest first in each rank. Keep that order. The introspection toggle does not apply.

Returns string-keyed rows: id, channel, title, goal, turn_count, created_at and modified_at. A match adds rank, the is_in_* flags and optional snippets.

The live view this handle drives is no longer open.

Raised by the next push after the human stopped watching — Escape in the terminal, Stop in the app — so an unattended loop ends by itself. A loop that would rather finish its own work reads view.is_interrupted instead and decides.

note is the comment the person left with the stop, when they left one: the reason it is being stopped, in their words.

One human action on a live view: change, submit, activate, select or shortcut.

value is the new value of a changed input; a secret input gives only is_set. values holds every input that a submit button collected. A Send in an app gives submission_id, the id of its receipt, and comments: the thread messages that it posted, each with node_id, thread_id, message_id, body and the anchor of a diff line. A pressed app shortcut gives action, the id that the shortcut sends, and key, the key that the person pressed. A shortcut that names a node gives an activate event of that node instead. A selection in a selectable table gives item_ids, the selected row ids.

A paragraph, heading or code block, replaced in place.

One node of a live view, addressed by its id.

One node of a live view, addressed by its id.

A titled card. A selectable card counts activations like a button.

One input component of a live view, read and set by id.

A secret input never shows its value: value is None for it, and its value arrives only in the submit event, as a vis-secret: handle.

One node of a live view, addressed by its id.

One node of a live view, addressed by its id.

One node of a live view, addressed by its id.

One node of a live view, addressed by its id.