web/browser/ remains a multi-file source package, but it registers one callable named playwright_browser. The explorer therefore shows one callable row instead of a redundant browser → playwright_browser pair. A source package becomes an expandable row only when it exports several callables.
Programs source categories
The Programs explorer follows the installed Python source hierarchy. Regular Functions are physically grouped by purpose under openprogram/programs/tools/; the UI reads that hierarchy instead of rebuilding unrelated folders from runtime tool metadata.
Source-backed, callable-first
Verified current implementation and gap
| Current boundary | Verified behavior | Gap |
|---|---|---|
tools | Purpose directories under openprogram/programs/tools/ hold deterministic @function packages. | None — public callable names stay unchanged. |
GET /api/tools | Returns runtime callables, including MCP-backed tools and display groups. | It remains a runtime/configuration endpoint and no longer defines Programs folders. |
GET /api/programs/explorer | Lists tools/, workflow/, and packages/ as callable-first rows. | None — leaf Workflow packages are not expandable. |
Classification contract
| Sidebar row | Canonical evidence | Items shown | Mutation |
|---|---|---|---|
tools | Physical directories beneath the installed package | files, web, knowledge, planning, agents, jobs, code, interaction, and runtime. | Read-only catalog |
tools/<purpose>/<module-or-package> | Physical Python source plus registration metadata | A singleton source is one callable row. A source that registers several callables is one expandable group containing those callable rows. | Favorite and Use operate on the callable |
workflow | Physical directories and modules under openprogram/programs/workflow/ | Each registered Workflow by its callable name, including multiple exports from one package. | Favorite and Use remain available |
packages | /api/programs/explorer | Installed Program packages. | Existing call tree and graph |
Reference comparison and decisions
| Reference | Relevant model | Decision here |
|---|---|---|
| OpenProgram registry | Regular functions and agentic functions register into one callable surface while retaining source-layer metadata. | Adopt the unified runtime catalog; add read-only source filters only in the management UI. |
| Hermes toolsets | Named toolsets represent selection, not source ownership. | Keep tool profiles separate from source categories. |
| Claude Code | The official repository does not publish the product's internal tool implementation tree, so its visible UI cannot establish a source-layout contract. | Do not copy an unverifiable one-folder-per-tool assumption. |
| OpenAI Codex | The public tool implementation uses both handler files and submodules. | Adopt the same complexity-based distinction, without copying Rust-specific names. |
Adopted: purpose directories are ordinary Python packages. A Function with one implementation file is a module; a Function or subsystem with providers, prompts, actions, workers, shared state, or several cooperating entry points is a package. A source package can register several callables, so packages such as agent and memory remain cohesive. Rejected: forcing every callable into a directory, forcing every source into one file, frontend-only categories, a second category registry, compatibility copies at old import paths, raw source-file browsing, and duplicating external MCP tools in Programs.
Physical source plan
| Directory | Packages moved into it |
|---|---|
files | apply_patch, bash, edit, glob, grep, list, process, read, write, worktree |
web | agent_browser, browser, image_analyze, image_generate, pdf, web_fetch, web_search |
knowledge | memory, read_conversation |
planning | plan_mode, todo |
agents | agent, mixture_of_agents, send_message |
jobs | cron |
code | execute_code, lsp, semble |
interaction | canvas, clarify, send_file |
runtime | mcp_meta, program, skill |
Single-file modules: apply_patch, edit, glob, grep, list, process, read, write, agent_browser, pdf, web_fetch, read_conversation, mixture_of_agents, execute_code, canvas, clarify, send_file, program, and skill. The remaining entries stay packages because they already contain cooperating implementation files or multiple registered callables.
Behavior, compatibility, and failures
- The explorer expands the installed directory hierarchy lazily; it never invents category paths in the browser.
- A singleton module or package is rendered directly as its registered callable; it does not add an extra source-wrapper row.
- A package that registers several callables expands to those callable names while retaining one shared source boundary.
- Refreshing Programs rescans Programs and reloads the same explorer endpoint.
- Rows whose source is
mcpnever appear in Programs; MCP Servers remains their only management page. - Agentic Functions use their public callable names; their source path is used only for static call analysis when available.
- Workflows, Applications, favorites, chat launch, call tree, and graph behavior remain unchanged.
Task brief and gate manifest
Production files: physical vanilla packages, their imports, the Programs explorer endpoint, and the existing Programs page. Test files: explorer public-entry tests, registry/import tests, and the Programs UI contract. Excluded: public callable renames, tool-profile policy changes, card restyling, dependencies, and external MCP catalog changes.
Acceptance: every shipped vanilla source lives under exactly one purpose directory; simple sources are modules and complex sources are packages; no old top-level source remains; playwright_browser is directly visible and retains tools/web/browser as its logic path; all registered vanilla callable names remain available; Workflows and Applications are unchanged.
Verification: focused explorer and registry RED/GREEN tests, import smoke test, Programs UI check, TypeScript compile, build, default 18100 packaged-App DOM and screenshot, and git diff --check.
Application import compatibility
Program packages loaded from openprogram/programs/packages must import built-in Agentic Functions through the canonical openprogram.programs.workflow namespace. The removed openprogram.programs.Agents namespace is not restored as a second compatibility package.
Acceptance: the packaged gui_agent public entry can begin a desktop run without a module-import error; the GUI, research, and wiki application packages contain no production import of the removed namespace.
Implementation status
In implementation: the physical purpose directories and callable registry are present. The remaining work is mixed module/package discovery, singleton-row projection, and final packaged-App verification.
Application function calls
The Application view reads current package source on each request. It starts at decorated public functions and follows local function calls and package imports, rather than treating every repository import as an execution edge. Tests, benchmarks and unrelated files do not enter the graph.
Conditional calls are labelled as conditional, not as a fixed execution sequence. The existing tree and graph share the same source-derived nodes. Unresolved calls and analysis limits are reported; the analyzer never executes package code to discover relationships. The visible page refreshes its analysis while open. The call tree initially expands the first three levels, keeping capability functions visible and their internals collapsed. Branch rows toggle with a click, Enter or Space. Expansion choices survive source refreshes for the selected Program; leaves and repeated references have no toggle.
Implementation status
Source tracing, conditional edges and visible-page refresh are implemented. Regression tests cover source edits, entry selection and unresolved callable aliases. Installed-App visual acceptance remains unverified. No Archify integration or Harness execution changes are included.