Programs code structure

1. Canonical directory contract

openprogram/
├── agentic_programming/
│   ├── llm.py                  # single model-call primitive
│   └── agent.py                # Agent-loop primitive with tool calls
└── programs/
    ├── tools/                  # deterministic, directly callable tools
    │   ├── files/  web/  code/  planning/  ...
    ├── workflow/               # all model reasoning, Agent orchestration, and composite capabilities
    │   ├── auto_workflow.py    # complete single-file Workflow; no empty same-name directory
    │   ├── goal/               # single Goal Workflow and session Goal mechanism
    │   │   ├── __init__.py
    │   │   ├── goal.py         # public entry goal()
    │   │   ├── command.py      # /goal command adapter
    │   │   ├── judge.py        # completion-condition evaluation
    │   │   ├── refinement.py   # goal specification and acceptance checklist
    │   │   ├── loop.py         # state transitions, retries, and stop rules of the single loop
    │   │   ├── state.py        # persistent state and events of the same GoalRun
    │   │   └── notices.py      # session status notifications
    │   ├── browser/  document/  research/  ...
    ├── packages/               # independent packages providing callable capabilities
    ├── _registry.py            # shared registration and discovery
    └── _programs.py            # Application provenance and installation metadata

2. Three Program categories

3. Basic primitives and Workflows

4. Goal has one execution function

4.1 Implementation and verification records

This section records reviewed implementation evidence only and does not alter the design contract above.

5. Choosing files and directories

Do not create same-name folders for every Workflow merely for uniformity. File count and responsibility boundaries determine package splitting.

6. Permitted dependency directions

7. Registration and Programs UI

8. One-time migration acceptance

9. Excluded designs

Source, registry, Programs explorer, and /goal all load according to this page’s directory contract. Source moves do not change public names or Schemas.

Installed Wiki prompt substitutions

The installed wiki_agent generation and enrichment prompts substitute only their declared content fields. Literal CSS examples such as alert-{info|warning|success|error} survive Python formatting unchanged; they are not substitution fields. Ingest and enrich reach their existing model and owned-vault operations without a formatting exception from the default prompt. The repair escapes those two literals in the existing prompt strings and preserves the Wiki generation, slot, Git and index mechanisms. Public acceptance invokes the actual registered entry for both actions, observes the unchanged literal at a controlled generation boundary, and verifies owned page and slot writes. The prompt literal repair has passed independent specification and quality reviews and is imported into the local package. Combined source and installed-interface acceptance are recorded separately.

Dynamic tool argument mappings

Canonical tool schemas distinguish mappings whose keys are provided at invocation time from objects with declared fields. The public program.args mapping accepts a registered program's legal keyword arguments, including task. Anonymous object mappings and Python dict/Mapping annotations retain open keys and any declared value schema. Objects with properties, including an empty declared property set, retain fixed-field closure. Explicit additionalProperties: false is never opened; nullable mappings retain their existing null behavior. Existing implicit-open top-level parameter objects are not newly closed by this repair.

The shared provider schema adapter must not turn an open mapping into an empty closed object. OpenAI function calling requires closed objects for strict mode and documents explicit strict: false to preserve non-strict behavior in Responses. Dynamic-mapping tools therefore use that explicit flag for Responses, Codex and Chat Completions; compatible fixed-field tools continue to use strict mode. Anthropic strict tool use similarly applies strict validation per tool; mapping tools retain the ordinary input schema without the strict flag. Existing provider availability, authentication, request-level feature gates and other schema dialects remain unchanged.

Acceptance uses the real public schema, production local validator and registered program consumer in an owned session. Valid task arguments reach the consumer; foreign programs and unsupported child keywords retain their existing errors, and wrong mapping types or values remain invalid. Production provider payloads preserve a dynamic mapping while a closed companion tool remains strict. The fixed execute_code schema remains strict and no dynamic parameter is added to it. Tests include fixed-object extra-key rejection, nullable and typed nested mappings, nonmutation, affected provider/program suites and repository contracts. Existing live sessions, App, worker and user state are excluded from controlled testing.

Implementation state: the canonical design is complete; implementation, independent specification review, fresh quality review and separate installed acceptance are pending.