PtcRunner.SubAgent.Loop.NativePreview (PtcRunner v0.12.0)

Copy Markdown View Source

Build LLM-facing native tool result previews for combined-mode agents.

Tier 2b of Plans/text-mode-ptc-compute-tool.md. When a tool is configured expose: :both, cache: true, the runtime stores the full result in state.tool_cache and returns a preview to the LLM. This module is the pure builder for that preview map.

Three preview shapes are supported, selected by the tool's native_result: option:

  • preview: :metadata (default / nil) — schema + sample keys + count.
  • preview: :rows — verbatim row sample capped at limit:.
  • preview: <fun/1> — custom builder receiving full_result only.

All three shapes are merged with the universal cache fields (status: "ok", full_result_cached: true, cache_hint: "<...>") before being returned. A custom-preview builder that raises, returns a non-map, or returns a non-Jason.encode!-able value falls back to the metadata preview and emits a Logger.warning/1 tagged with the tool name and failure category.

See the plan doc's "Native Tool Result Preview" → "Default Metadata Preview — Inference Rules" table for the exact metadata shape; this module is the canonical implementation of that table.

Used by PtcRunner.SubAgent.Loop.TextMode in combined mode.

Summary

Types

preview_status()

Functions

build(tool, full_result, args)

Build a preview map for full_result per tool.native_result.

cache_hint(tool_name, args)

Render the cache_hint string for a native preview.

Types

preview_status()

@type preview_status() :: :ok | :fallback

Functions

build(tool, full_result, args)

@spec build(PtcRunner.Tool.t(), term(), map()) :: {preview_status(), map()}

Build a preview map for full_result per tool.native_result.

Returns {:ok, preview} for the default-success path or {:fallback, preview} when a custom preview builder failed and the metadata preview was used as a recovery. Both shapes are Jason-encodable and carry the universal cache fields (status, full_result_cached, cache_hint).

args is the canonical args map (post-KeyNormalizer normalization) used to render the cache_hint's (tool/<name> <ARGS_FRAGMENT>) example. Pass the raw args; the helper canonicalizes internally.

cache_hint(tool_name, args)

@spec cache_hint(String.t(), map()) :: String.t()

Render the cache_hint string for a native preview.

Format:

Call lisp_eval and then call (tool/<name> <ARGS>) to
process the full cached result.

<ARGS> is produced by PtcRunner.Lisp.Formatter.format/1 after converting the canonical args map to PTC-Lisp AST per the conversion table in Addendum #26 of the plan. Strings, nested maps, vectors, and keyword keys all round-trip through Formatter — no hand-rolled escaping in this module.