nsaspy/prolog-rlm

Fork 0

[P1] Add reusable in-repo standard tool packs outside core #50

New issue

Closed

opened 2026-08-16 04:01:16 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-16 04:01:16 +00:00

(Migrated from github.com)

Goal

Provide a separately loadable standard tool pack maintained in the same lost-rob0t/prolog-rlm repository by default for agents built on prolog-rlm, without expanding core authority or making the core runtime depend on concrete production tools.

This is the standard in-repo concrete tool catalog. It is external to the core runtime dependency graph, not required to live in a separate Git repository. Third-party packs may still live elsewhere and use the same loader ABI.

Category model

Every concrete tool belongs to one or more advertised categories. The standard in-repo packs must support the core loading API:

rlm_load_tools(Registry, filesystem, Outcome).
rlm_load_tools(Registry, git, Outcome).
rlm_load_tools(Registry, forge, Outcome).
rlm_load_tools(Registry, process, Outcome).
rlm_load_tools(Registry, network, Outcome).
rlm_load_tools(Registry, mcp, Outcome).

rlm_load_all_tools(Registry, Outcome).

Category loading controls which tool schemas/handlers are registered and available. It does not grant invocation capabilities or authority.

Repository/layout contract

The standard packages should remain visibly separated from core while sharing the same checkout, CI, versioning and issue tracker. Exact paths may be refined, but the intended shape is equivalent to:

prolog-rlm/
  prolog/                 # reusable domain-neutral core
  tools/ or packs/
    filesystem/
    git/
    forge/
      common forge contract
      GitHub adapter
      Forgejo adapter
    process/
    network/

Core must not import these production packs automatically.

Initial tool set by category

filesystem

project_read — migrated from core;
project_search — bounded search under an explicit project root.

git

Initial read-only surface:

git_status;
git_diff;
git_show.

Follow-on write surface for self-hosting/coding harnesses must remain typed and structured rather than arbitrary shell text, including operations such as branch/worktree creation, expected-head patch application, commit, fetch and push. Repository mutations must compose with normal authority and durable-effect semantics.

forge

Add a backend-neutral forge vocabulary with first-party adapters for GitHub and Forgejo.

The common model should cover normalized repository collaboration operations rather than exposing arbitrary HTTP paths. Initial/follow-on tool surfaces should include bounded typed operations for:

repository metadata;
issue read/list/create/comment/update where permitted;
pull/merge-request read/list/create/comment/review where permitted;
branch/commit/status/CI observations;
explicit merge only as a distinct high-authority operation.

Provider adapters:

forge common contract
  -> GitHub API adapter
  -> Forgejo API adapter

Git remote transport and local repository operations remain owned by the git category; issues/PRs/reviews/CI and forge metadata belong to forge.

Do not expose one generic model tool that accepts arbitrary forge API URLs/methods. Model-visible operations must use closed schemas and bounded semantics.

process

run_tests — bounded execution of an explicitly configured test command/profile;
process_run — narrowly configured process execution with command allow-list/profile, timeout, cwd confinement, environment filtering, and output limits.

network

http_get — bounded HTTP GET with explicit network capability, timeout, redirect, response-size, and scheme/host policy.

mcp

MCP tool import/adapter support so selected MCP tools can be registered through the same RLM tool contract;
declarative MCP server facts and lifecycle integration remain separate from loading;
loading the MCP category does not automatically install/start/connect every declared server.

Capability/authority direction

Availability is separate from permission. Prefer narrow operation capabilities rather than a single ambient git or forge superpower where write-risk differs materially.

Examples of capability classes to design against:

tool(git_status)
tool(git_diff)
tool(git_commit)
tool(git_push)

tool(forge_issue_read)
tool(forge_issue_write)
tool(forge_pr_read)
tool(forge_pr_write)
tool(forge_review)
tool(forge_merge)

Exact names follow implementation conventions. forge_merge must remain separately grantable from ordinary issue/PR work.

Acceptance criteria

Standard concrete tool packages are maintained in this repository by default but are not dependencies of the core runtime.
Third-party packs can remain independently hosted and use the same loader/manifest ABI.
Every tool advertises a stable category and explicit schema/capability/effect metadata.
rlm_load_tools/3 can register all standard tools in one category without registering unrelated categories.
rlm_load_all_tools/2 registers the installed standard set without granting capabilities or changing authority.
Category loading is deterministic and safe to repeat.
The category registry is discoverable so callers can enumerate available categories/tools.
Filesystem tools are confined to configured roots.
Process execution is never arbitrary shell text from model output.
Network access is explicit and policy-bounded.
Git read operations are implemented first; Git write operations are typed, expected-state aware, and authority/effect mediated when added.
A backend-neutral forge contract supports both GitHub and Forgejo without pretending their APIs are identical.
Forge mutations use closed typed operations, explicit capabilities, host authority, durable effect identity, structured errors, and conservative uncertainty where remote outcome is unknown.
Merge is a distinct capability/authority boundary and is not implied by PR creation/review capability.
Tool outputs are byte-bounded and structured.
Invocation timeouts and traces use the existing rlm_tool contract.
Latency-bearing tool operations use the canonical async execution path.
Deterministic allow/deny, category-loading, all-loading, malformed-input, provider-adapter, and concurrency/expected-state tests exist for each relevant family.
The packages are independently usable by multiple downstream harnesses.

Non-goals

No hidden ambient shell.
No implicit write access to repositories.
No dependency from prolog-rlm core back onto the standard concrete tool packages.
No requirement to split standard tool families into separate Git repositories.
Loading all tools must never imply granting all capabilities.
No generic arbitrary GitHub/Forgejo HTTP request tool exposed to the model.
Loading the MCP category must not auto-install or auto-run all MCP servers.

## Goal Provide a separately loadable **standard tool pack maintained in the same `lost-rob0t/prolog-rlm` repository by default** for agents built on `prolog-rlm`, without expanding core authority or making the core runtime depend on concrete production tools. This is the standard in-repo concrete tool catalog. It is external to the **core runtime dependency graph**, not required to live in a separate Git repository. Third-party packs may still live elsewhere and use the same loader ABI. ## Category model Every concrete tool belongs to one or more advertised categories. The standard in-repo packs must support the core loading API: ```prolog rlm_load_tools(Registry, filesystem, Outcome). rlm_load_tools(Registry, git, Outcome). rlm_load_tools(Registry, forge, Outcome). rlm_load_tools(Registry, process, Outcome). rlm_load_tools(Registry, network, Outcome). rlm_load_tools(Registry, mcp, Outcome). rlm_load_all_tools(Registry, Outcome). ``` Category loading controls which tool schemas/handlers are registered and available. It does **not** grant invocation capabilities or authority. ## Repository/layout contract The standard packages should remain visibly separated from core while sharing the same checkout, CI, versioning and issue tracker. Exact paths may be refined, but the intended shape is equivalent to: ```text prolog-rlm/ prolog/ # reusable domain-neutral core tools/ or packs/ filesystem/ git/ forge/ common forge contract GitHub adapter Forgejo adapter process/ network/ ``` Core must not import these production packs automatically. ## Initial tool set by category ### filesystem - `project_read` — migrated from core; - `project_search` — bounded search under an explicit project root. ### git Initial read-only surface: - `git_status`; - `git_diff`; - `git_show`. Follow-on write surface for self-hosting/coding harnesses must remain typed and structured rather than arbitrary shell text, including operations such as branch/worktree creation, expected-head patch application, commit, fetch and push. Repository mutations must compose with normal authority and durable-effect semantics. ### forge Add a backend-neutral forge vocabulary with first-party adapters for **GitHub and Forgejo**. The common model should cover normalized repository collaboration operations rather than exposing arbitrary HTTP paths. Initial/follow-on tool surfaces should include bounded typed operations for: - repository metadata; - issue read/list/create/comment/update where permitted; - pull/merge-request read/list/create/comment/review where permitted; - branch/commit/status/CI observations; - explicit merge only as a distinct high-authority operation. Provider adapters: ```text forge common contract -> GitHub API adapter -> Forgejo API adapter ``` Git remote transport and local repository operations remain owned by the `git` category; issues/PRs/reviews/CI and forge metadata belong to `forge`. Do not expose one generic model tool that accepts arbitrary forge API URLs/methods. Model-visible operations must use closed schemas and bounded semantics. ### process - `run_tests` — bounded execution of an explicitly configured test command/profile; - `process_run` — narrowly configured process execution with command allow-list/profile, timeout, cwd confinement, environment filtering, and output limits. ### network - `http_get` — bounded HTTP GET with explicit network capability, timeout, redirect, response-size, and scheme/host policy. ### mcp - MCP tool import/adapter support so selected MCP tools can be registered through the same RLM tool contract; - declarative MCP server facts and lifecycle integration remain separate from loading; - loading the MCP category does not automatically install/start/connect every declared server. ## Capability/authority direction Availability is separate from permission. Prefer narrow operation capabilities rather than a single ambient `git` or `forge` superpower where write-risk differs materially. Examples of capability classes to design against: ```text tool(git_status) tool(git_diff) tool(git_commit) tool(git_push) tool(forge_issue_read) tool(forge_issue_write) tool(forge_pr_read) tool(forge_pr_write) tool(forge_review) tool(forge_merge) ``` Exact names follow implementation conventions. `forge_merge` must remain separately grantable from ordinary issue/PR work. ## Acceptance criteria - [ ] Standard concrete tool packages are maintained in this repository by default but are not dependencies of the core runtime. - [ ] Third-party packs can remain independently hosted and use the same loader/manifest ABI. - [ ] Every tool advertises a stable category and explicit schema/capability/effect metadata. - [ ] `rlm_load_tools/3` can register all standard tools in one category without registering unrelated categories. - [ ] `rlm_load_all_tools/2` registers the installed standard set without granting capabilities or changing authority. - [ ] Category loading is deterministic and safe to repeat. - [ ] The category registry is discoverable so callers can enumerate available categories/tools. - [ ] Filesystem tools are confined to configured roots. - [ ] Process execution is never arbitrary shell text from model output. - [ ] Network access is explicit and policy-bounded. - [ ] Git read operations are implemented first; Git write operations are typed, expected-state aware, and authority/effect mediated when added. - [ ] A backend-neutral forge contract supports both GitHub and Forgejo without pretending their APIs are identical. - [ ] Forge mutations use closed typed operations, explicit capabilities, host authority, durable effect identity, structured errors, and conservative uncertainty where remote outcome is unknown. - [ ] Merge is a distinct capability/authority boundary and is not implied by PR creation/review capability. - [ ] Tool outputs are byte-bounded and structured. - [ ] Invocation timeouts and traces use the existing `rlm_tool` contract. - [ ] Latency-bearing tool operations use the canonical async execution path. - [ ] Deterministic allow/deny, category-loading, all-loading, malformed-input, provider-adapter, and concurrency/expected-state tests exist for each relevant family. - [ ] The packages are independently usable by multiple downstream harnesses. ## Non-goals - No hidden ambient shell. - No implicit write access to repositories. - No dependency from `prolog-rlm` core back onto the standard concrete tool packages. - No requirement to split standard tool families into separate Git repositories. - Loading all tools must never imply granting all capabilities. - No generic arbitrary GitHub/Forgejo HTTP request tool exposed to the model. - Loading the MCP category must not auto-install or auto-run all MCP servers.

nsaspy referenced this issue

2026-08-27 20:02:03 +00:00

Canonical async tool + MCP runtime slice #60

nsaspy referenced this issue

2026-08-27 20:02:03 +00:00

Harden external tool category loading boundary #66

nsaspy referenced this issue

2026-08-27 20:02:05 +00:00

Reconcile backlog, roadmap, and GitHub issue state #89

nsaspy closed this issue

2026-09-08 01:28:59 +00:00

nsaspy commented

2026-09-08 01:31:48 +00:00

Owner

Closing as superseded by #141. The restored canonical boundary puts concrete coding/project tool catalogs (filesystem/Git/process/test/forge product packs) downstream in lost-rob0t/agentProlog. prolog-rlm retains the generic tool/registry/capability/authority/effect contracts. The new expert-system layer will consume typed host-supplied capabilities rather than moving concrete product tools back into this repository.

Closing as **superseded by #141**. The restored canonical boundary puts concrete coding/project tool catalogs (filesystem/Git/process/test/forge product packs) downstream in `lost-rob0t/agentProlog`. `prolog-rlm` retains the generic tool/registry/capability/authority/effect contracts. The new expert-system layer will consume typed host-supplied capabilities rather than moving concrete product tools back into this repository.

nsaspy referenced this issue

2026-09-10 21:18:01 +00:00

[P1] Define dual synchronous/asynchronous API contract across RLM libraries #425

nsaspy referenced this issue

2026-09-10 21:18:07 +00:00

[EPIC] Add durable scoped state and Prolog-native project policy configuration #432

nsaspy referenced this issue

2026-09-10 21:18:10 +00:00

[P1] Define a safe Prolog-native project policy/config pack boundary #435