Spaces:

User1342
/

distinct

Running on Zero

initial commit

2aa8b3a about 2 months ago

15 kB

"""Explicit, policy-bounded tools for local inference agents.
**Nothing is approved until an operator approves it, so the default registry is
still empty.** That has not changed, and it is what keeps the runtime's
no-outbound-request claim literally true out of the box.  What has changed is
that there is now something to approve.
This package is the tool *framework* and a small, evidence-chosen tool set:
* versioned specs with JSON schemas, exact ``id@version`` references, per-job
  policy (allowlist, call quotas, timeouts, byte caps, host permissions) and a
  per-job :class:`ToolBroker` that snapshots the registry so a later
  registration cannot widen a running job;
* :mod:`distinct_tools.local`, six local tools that open no socket, read no
  file and spawn no process: ``calculate``, ``calculate_date``,
  ``convert_units``, ``extract_from_text``, ``search_document`` and
  ``verify_quote``.  Every one answers in a single call, which is the
  criterion that decides what is viable below 7B;
* :mod:`distinct_tools.approval`, the operator's own allowlist, which is
  checked before the server's and cannot be widened remotely;
* :mod:`distinct_tools.mcp`, which maps Model Context Protocol servers onto the
  same specs, brokers and policies rather than beside them;
* :mod:`distinct_tools.trace`, a bounded record of every call attempted,
  including every refusal.
Two more sources of library members exist outside this package and reach the
registry through :func:`default_registry`: :mod:`distinct_skills`, a repository
of skills held on disk and digest-pinned, and :mod:`distinct_mcp`, four
in-process MCP servers. Both produce ordinary specs in the ordinary registry.
**The three sources are not approved the same way, and the difference is the
whole safety argument.** ``DISTINCT_APPROVED_TOOLS=local`` is a bundle name,
and :func:`~distinct_tools.approval.load_policy` expands it to "every spec in
the list it was given that declares no host". So the list handed to
``load_policy`` decides what one word approves, and it is deliberately
:data:`INSTALLABLE_SPECS` and nothing else. A repository skill or an MCP tool
is reachable only by naming its exact ``id@version``: they are filtered with
``policy.permitted_specs(...)``, which works on refs already approved and never
expands a bundle. Widening the list passed to ``load_policy`` would silently
put ``files.write_file@1``, which reads and writes a directory on a
volunteer's machine, inside a single flag. There is a test that fails if
anybody does.
**The catalogue is small on purpose.**
:data:`~distinct_tools.approval.MAX_APPROVED_TOOLS` caps one operator at 64
approved refs, because a large menu costs selection accuracy on a small model.
Everything this repository can offer today, the ten library members, the four
repository skills and the eight MCP tools, comes to twenty-two, so the cap is
not currently reachable by approving everything. At the boundary the failure is
closed and loud rather than partial: ``OperatorPolicy`` raises,
``load_policy`` catches it, and what comes back approves nothing at all with
the reason in ``source``. A truncated approval list would be worse, because the
operator would believe they had approved something they had not.
Three gates stand between a tool existing and a tool running, and all three
must open:
1. it is **installed** (registered, and for MCP its definition digest still
   matches what was approved);
2. the **operator** approved it, and separately approved network access if it
   declares any host;
3. the **run** selected it, through ``JobSpec.allowed_tools``.
Any tool failing any gate fails closed and the attempt is recorded on
:attr:`ToolBroker.trace`.  With nothing approved, gate 2 refuses everything,
no reference resolves, and the agent makes no outbound request.
:mod:`distinct_tools.testing` holds inert fixtures used to keep the framework's
own tests honest.  Nothing there is ever auto-registered.
"""

from collections.abc import Mapping

from .approval import (
    APPROVED_EGRESS_ENV_VAR,
    APPROVED_TOOLS_ENV_VAR,
    DENY_ALL,
    LOCAL_BUNDLE,
    POLICY_FILE_ENV_VAR,
    OperatorPolicy,
    ToolPolicyError,
    load_policy,
)
from .core import (
    JobPolicy,
    OperatorRefusal,
    Registry,
    ToolBroker,
    ToolCallError,
    ToolContext,
    ToolInputError,
    ToolRef,
    ToolResult,
    ToolSpec,
    normalize_host,
)
from .local import LOCAL_SPECS, register_local_tools
from .skills import (
    REPOSITORY_SKILLS,
    REPOSITORY_SPECS,
    REPOSITORY_STATUS,
    SKILL_SPECS,
    describe_skill_repository,
    install_skill_repository,
    register_skills,
)
from .workspace import WORKSPACE_SPECS, register_workspace_tools
from .trace import ToolCallRecord, ToolTrace, describe_for_agent

#: The library members written in this package: the local tools and the local
#: skills. Tools and skills are one library behind one policy; a skill differs
#: only in returning an artifact for the user rather than an in-band answer.
#:
#: This tuple is also the list the ``local`` bundle expands over, which is why
#: the repository skills and the MCP tools are not in it. Both of those are
#: installed by :func:`default_registry` when an operator names them in full,
#: and neither can be reached by the bundle name.
INSTALLABLE_SPECS: tuple[ToolSpec, ...] = LOCAL_SPECS + SKILL_SPECS + WORKSPACE_SPECS


def operator_policy(*, environ: Mapping[str, str] | None = None) -> OperatorPolicy:
    """Read the operator's approval policy for the installable tool set."""

    return load_policy(INSTALLABLE_SPECS, environ=environ)


def _install_mcp_catalogue(
    registry: Registry,
    policy: OperatorPolicy,
    environ: Mapping[str, str] | None,
) -> tuple[frozenset[ToolRef], tuple[str, ...]]:
    """Install the MCP tools the operator named, and report what was not.
    Returns the refs the catalogue recognised, installed or not, so the caller
    can tell an approved ref that this package could not offer apart from one
    that nothing anywhere has heard of.
    """

    # Nothing was approved that the two local sources do not already cover, so
    # there is no MCP work to do. Returning before the import keeps an
    # operator who never asked for MCP from being told about it, and it is the
    # difference between "you approved an MCP tool and could not have it" and
    # a message about a package they were not using.
    known = frozenset(spec.ref for spec in INSTALLABLE_SPECS)
    known |= frozenset(spec.ref for spec in REPOSITORY_SPECS)
    unknown = policy.approved - known
    if not unknown:
        return frozenset(), ()

    # Imported here rather than at the top of the module because
    # ``distinct_mcp`` imports ``distinct_tools``, and the cycle is the only
    # reason for the deferral. It is worth being exact about how it fails,
    # because half the time it does not: with the import at module level,
    # ``import distinct_tools`` still works, and ``import distinct_mcp`` first
    # raises ImportError for a partially initialised module, because this
    # module then runs part-way through that one. Anybody who tries the move
    # and checks only the first order will conclude it is fine.
    try:
        from distinct_mcp import install_catalogue
    except ImportError as exc:
        # Every unresolved ref is counted as accounted for here, even though
        # one of them may be a plain typo. Without the package there is no way
        # to tell the two apart, and the message below is the true one; adding
        # "check the spelling" on top of it would send the operator looking for
        # a mistake they did not make.
        return unknown, (
            f"MCP tools were approved but distinct_mcp could not be imported ({exc}), "
            "so none of them is installed and every call to them fails closed",
        )
    result = install_catalogue(
        registry, only=policy.approved, egress=policy.egress_approved, environ=environ
    )
    return frozenset(result.refs) | frozenset(result.skipped), result.notes


def _build_registry(
    environ: Mapping[str, str] | None = None,
) -> tuple[Registry, tuple[str, ...]]:
    """Build the registry and collect anything the operator should be told.
    Split from :func:`default_registry` so that the notes have somewhere to go.
    A capability an operator approved and did not get is exactly the fact they
    need, and returning only a registry leaves nowhere to put it.
    """

    registry = Registry()
    notes: list[str] = []

    # LOAD-BEARING: the policy is read against INSTALLABLE_SPECS and nothing
    # else, because the ``local`` bundle expands over whatever list it is
    # given. Adding the repository or the MCP specs here would put a skill
    # read off the disk, and a tool that writes files, inside one flag.
    policy = load_policy(INSTALLABLE_SPECS, environ=environ)
    if not policy.approved:
        return registry, ()

    approved = frozenset(spec.ref for spec in policy.permitted_specs(INSTALLABLE_SPECS))
    if approved:
        register_local_tools(registry, only=approved)
        register_skills(registry, only=approved)
        register_workspace_tools(registry, only=approved)

    # permitted_specs filters refs the operator already approved and expands
    # nothing, so this cannot widen the bundle however the repository grows.
    repository = frozenset(spec.ref for spec in policy.permitted_specs(REPOSITORY_SPECS))
    if repository:
        try:
            install_skill_repository(registry, only=repository)
        except (ValueError, RuntimeError) as exc:
            # A duplicate identifier or an unresolvable handler: both are bugs
            # in this repository rather than operator error. The worker still
            # runs everything else, and says which one it dropped, because a
            # worker that refuses every tool over one broken skill is worse.
            notes.append(f"the skill repository could not be installed ({exc})")

    accounted, mcp_notes = _install_mcp_catalogue(registry, policy, environ)
    notes.extend(mcp_notes)

    installed = frozenset(spec.ref for spec in registry.specs())
    unmatched = sorted(
        policy.approved - installed - accounted, key=lambda ref: (ref.tool_id, ref.version)
    )
    for ref in unmatched:
        # Almost always a typo. Saying so beats leaving the operator to work
        # out why a tool they approved never appears in what the worker offers.
        notes.append(
            f"{ref.tool_id}@{ref.version} is approved but nothing installs it; check the "
            "spelling against the list of approvable refs"
        )
    return registry, tuple(notes)


def default_registry(*, environ: Mapping[str, str] | None = None) -> Registry:
    """Return the agent's tool registry: only what the operator approved.
    There is still no entry-point discovery, import scanning or dynamic module
    loading, and no credential-gated registration.  A tool appears here only
    because a human named it in :data:`~distinct_tools.approval.APPROVED_TOOLS_ENV_VAR`
    or a policy file.  With neither set, this returns an empty registry and
    every tool call fails closed.
    Three sources feed it and all three obey the same gate. The library members
    in :data:`INSTALLABLE_SPECS` are registered directly; the skills in
    :mod:`distinct_skills` are installed from their pinned directories; the MCP
    servers in :mod:`distinct_mcp` are built and installed. A server that is
    approved but cannot be built is skipped rather than fatal, and the reason
    is available from :func:`registry_notes`.
    Re-read on each call rather than cached, so an operator who changes their
    approvals does not have to restart the worker.  A run already in flight is
    unaffected: :class:`ToolBroker` snapshots the registry at construction.
    Building an MCP server here is still discovery at install time in the sense
    :mod:`distinct_tools.mcp` means it: it happens before the job's broker
    exists, the broker then snapshots, and no run ever negotiates with a
    server. The servers are in-process code from this repository, so the
    listing costs no I/O beyond the file server resolving its directory.
    """

    return _build_registry(environ)[0]


def registry_notes(*, environ: Mapping[str, str] | None = None) -> tuple[str, ...]:
    """Say what the operator approved and did not get, and why.
    Empty when everything approved was installed. Anything here is a capability
    the worker is not offering despite being told to, which is a fact that has
    to reach a person: the alternatives are failing open, or a silence that
    reads as success.
    """

    return _build_registry(environ)[1]


def approvable_refs() -> tuple[str, ...]:
    """Every ``id@version`` an operator could name today, from all three sources.
    Not filtered by what is approved: this is the menu, not the order. The MCP
    half is derived from the catalogue's manifests rather than by building the
    servers, so the file server appears here whether or not a directory has
    been nominated for it yet.
    """

    refs = {f"{spec.tool_id}@{spec.version}" for spec in INSTALLABLE_SPECS}
    refs |= {f"{spec.tool_id}@{spec.version}" for spec in REPOSITORY_SPECS}
    try:
        from distinct_mcp import catalogue_refs  # deferred: see _install_mcp_catalogue
    except ImportError:  # pragma: no cover - distinct_mcp is part of this repository
        return tuple(sorted(refs))
    return tuple(sorted(refs | set(catalogue_refs())))


def available_tool_refs(*, environ: Mapping[str, str] | None = None) -> tuple[str, ...]:
    """Detect approved, installed capabilities as sorted ``id@version`` refs.
    This is what the worker advertises.  A tool the operator has not approved
    is never advertised, so a server cannot select it in the first place; the
    broker refuses it again if one tries anyway.
    """

    return tuple(sorted(f"{spec.tool_id}@{spec.version}" for spec in default_registry(environ=environ).specs()))


__all__ = [
    "APPROVED_EGRESS_ENV_VAR",
    "APPROVED_TOOLS_ENV_VAR",
    "DENY_ALL",
    "INSTALLABLE_SPECS",
    "REPOSITORY_SKILLS",
    "REPOSITORY_SPECS",
    "REPOSITORY_STATUS",
    "describe_skill_repository",
    "install_skill_repository",
    "LOCAL_BUNDLE",
    "LOCAL_SPECS",
    "POLICY_FILE_ENV_VAR",
    "JobPolicy",
    "OperatorPolicy",
    "OperatorRefusal",
    "Registry",
    "ToolBroker",
    "ToolCallError",
    "ToolCallRecord",
    "ToolContext",
    "ToolInputError",
    "ToolPolicyError",
    "ToolRef",
    "ToolResult",
    "ToolSpec",
    "ToolTrace",
    "approvable_refs",
    "available_tool_refs",
    "default_registry",
    "describe_for_agent",
    "SKILL_SPECS",
    "load_policy",
    "normalize_host",
    "operator_policy",
    "register_local_tools",
    "register_skills",
    "register_workspace_tools",
    "registry_notes",
    "WORKSPACE_SPECS",
]

	"""Explicit, policy-bounded tools for local inference agents.

	**Nothing is approved until an operator approves it, so the default registry is
	still empty.** That has not changed, and it is what keeps the runtime's
	no-outbound-request claim literally true out of the box. What has changed is
	that there is now something to approve.

	This package is the tool framework and a small, evidence-chosen tool set:

	* versioned specs with JSON schemas, exact ``id@version`` references, per-job
	policy (allowlist, call quotas, timeouts, byte caps, host permissions) and a
	per-job :class:`ToolBroker` that snapshots the registry so a later
	registration cannot widen a running job;
	* :mod:`distinct_tools.local`, six local tools that open no socket, read no
	file and spawn no process: ``calculate``, ``calculate_date``,
	``convert_units``, ``extract_from_text``, ``search_document`` and
	``verify_quote``. Every one answers in a single call, which is the
	criterion that decides what is viable below 7B;
	* :mod:`distinct_tools.approval`, the operator's own allowlist, which is
	checked before the server's and cannot be widened remotely;
	* :mod:`distinct_tools.mcp`, which maps Model Context Protocol servers onto the
	same specs, brokers and policies rather than beside them;
	* :mod:`distinct_tools.trace`, a bounded record of every call attempted,
	including every refusal.

	Two more sources of library members exist outside this package and reach the
	registry through :func:`default_registry`: :mod:`distinct_skills`, a repository
	of skills held on disk and digest-pinned, and :mod:`distinct_mcp`, four
	in-process MCP servers. Both produce ordinary specs in the ordinary registry.

	**The three sources are not approved the same way, and the difference is the
	whole safety argument.** ``DISTINCT_APPROVED_TOOLS=local`` is a bundle name,
	and :func:`~distinct_tools.approval.load_policy` expands it to "every spec in
	the list it was given that declares no host". So the list handed to
	``load_policy`` decides what one word approves, and it is deliberately
	:data:`INSTALLABLE_SPECS` and nothing else. A repository skill or an MCP tool
	is reachable only by naming its exact ``id@version``: they are filtered with
	``policy.permitted_specs(...)``, which works on refs already approved and never
	expands a bundle. Widening the list passed to ``load_policy`` would silently
	put ``files.write_file@1``, which reads and writes a directory on a
	volunteer's machine, inside a single flag. There is a test that fails if
	anybody does.

	The catalogue is small on purpose.
	:data:`~distinct_tools.approval.MAX_APPROVED_TOOLS` caps one operator at 64
	approved refs, because a large menu costs selection accuracy on a small model.
	Everything this repository can offer today, the ten library members, the four
	repository skills and the eight MCP tools, comes to twenty-two, so the cap is
	not currently reachable by approving everything. At the boundary the failure is
	closed and loud rather than partial: ``OperatorPolicy`` raises,
	``load_policy`` catches it, and what comes back approves nothing at all with
	the reason in ``source``. A truncated approval list would be worse, because the
	operator would believe they had approved something they had not.

	Three gates stand between a tool existing and a tool running, and all three
	must open:

	1. it is installed (registered, and for MCP its definition digest still
	matches what was approved);
	2. the operator approved it, and separately approved network access if it
	declares any host;
	3. the run selected it, through ``JobSpec.allowed_tools``.

	Any tool failing any gate fails closed and the attempt is recorded on
	:attr:`ToolBroker.trace`. With nothing approved, gate 2 refuses everything,
	no reference resolves, and the agent makes no outbound request.

	:mod:`distinct_tools.testing` holds inert fixtures used to keep the framework's
	own tests honest. Nothing there is ever auto-registered.
	"""

	from collections.abc import Mapping

	from .approval import (
	APPROVED_EGRESS_ENV_VAR,
	APPROVED_TOOLS_ENV_VAR,
	DENY_ALL,
	LOCAL_BUNDLE,
	POLICY_FILE_ENV_VAR,
	OperatorPolicy,
	ToolPolicyError,
	load_policy,
	)
	from .core import (
	JobPolicy,
	OperatorRefusal,
	Registry,
	ToolBroker,
	ToolCallError,
	ToolContext,
	ToolInputError,
	ToolRef,
	ToolResult,
	ToolSpec,
	normalize_host,
	)
	from .local import LOCAL_SPECS, register_local_tools
	from .skills import (
	REPOSITORY_SKILLS,
	REPOSITORY_SPECS,
	REPOSITORY_STATUS,
	SKILL_SPECS,
	describe_skill_repository,
	install_skill_repository,
	register_skills,
	)
	from .workspace import WORKSPACE_SPECS, register_workspace_tools
	from .trace import ToolCallRecord, ToolTrace, describe_for_agent

	#: The library members written in this package: the local tools and the local
	#: skills. Tools and skills are one library behind one policy; a skill differs
	#: only in returning an artifact for the user rather than an in-band answer.
	#:
	#: This tuple is also the list the ``local`` bundle expands over, which is why
	#: the repository skills and the MCP tools are not in it. Both of those are
	#: installed by :func:`default_registry` when an operator names them in full,
	#: and neither can be reached by the bundle name.
	INSTALLABLE_SPECS: tuple[ToolSpec, ...] = LOCAL_SPECS + SKILL_SPECS + WORKSPACE_SPECS


	def operator_policy(*, environ: Mapping[str, str] \| None = None) -> OperatorPolicy:
	"""Read the operator's approval policy for the installable tool set."""

	return load_policy(INSTALLABLE_SPECS, environ=environ)


	def _install_mcp_catalogue(
	registry: Registry,
	policy: OperatorPolicy,
	environ: Mapping[str, str] \| None,
	) -> tuple[frozenset[ToolRef], tuple[str, ...]]:
	"""Install the MCP tools the operator named, and report what was not.

	Returns the refs the catalogue recognised, installed or not, so the caller
	can tell an approved ref that this package could not offer apart from one
	that nothing anywhere has heard of.
	"""

	# Nothing was approved that the two local sources do not already cover, so
	# there is no MCP work to do. Returning before the import keeps an
	# operator who never asked for MCP from being told about it, and it is the
	# difference between "you approved an MCP tool and could not have it" and
	# a message about a package they were not using.
	known = frozenset(spec.ref for spec in INSTALLABLE_SPECS)
	known \|= frozenset(spec.ref for spec in REPOSITORY_SPECS)
	unknown = policy.approved - known
	if not unknown:
	return frozenset(), ()

	# Imported here rather than at the top of the module because
	# ``distinct_mcp`` imports ``distinct_tools``, and the cycle is the only
	# reason for the deferral. It is worth being exact about how it fails,
	# because half the time it does not: with the import at module level,
	# ``import distinct_tools`` still works, and ``import distinct_mcp`` first
	# raises ImportError for a partially initialised module, because this
	# module then runs part-way through that one. Anybody who tries the move
	# and checks only the first order will conclude it is fine.
	try:
	from distinct_mcp import install_catalogue
	except ImportError as exc:
	# Every unresolved ref is counted as accounted for here, even though
	# one of them may be a plain typo. Without the package there is no way
	# to tell the two apart, and the message below is the true one; adding
	# "check the spelling" on top of it would send the operator looking for
	# a mistake they did not make.
	return unknown, (
	f"MCP tools were approved but distinct_mcp could not be imported ({exc}), "
	"so none of them is installed and every call to them fails closed",
	)
	result = install_catalogue(
	registry, only=policy.approved, egress=policy.egress_approved, environ=environ
	)
	return frozenset(result.refs) \| frozenset(result.skipped), result.notes


	def _build_registry(
	environ: Mapping[str, str] \| None = None,
	) -> tuple[Registry, tuple[str, ...]]:
	"""Build the registry and collect anything the operator should be told.

	Split from :func:`default_registry` so that the notes have somewhere to go.
	A capability an operator approved and did not get is exactly the fact they
	need, and returning only a registry leaves nowhere to put it.
	"""

	registry = Registry()
	notes: list[str] = []

	# LOAD-BEARING: the policy is read against INSTALLABLE_SPECS and nothing
	# else, because the ``local`` bundle expands over whatever list it is
	# given. Adding the repository or the MCP specs here would put a skill
	# read off the disk, and a tool that writes files, inside one flag.
	policy = load_policy(INSTALLABLE_SPECS, environ=environ)
	if not policy.approved:
	return registry, ()

	approved = frozenset(spec.ref for spec in policy.permitted_specs(INSTALLABLE_SPECS))
	if approved:
	register_local_tools(registry, only=approved)
	register_skills(registry, only=approved)
	register_workspace_tools(registry, only=approved)

	# permitted_specs filters refs the operator already approved and expands
	# nothing, so this cannot widen the bundle however the repository grows.
	repository = frozenset(spec.ref for spec in policy.permitted_specs(REPOSITORY_SPECS))
	if repository:
	try:
	install_skill_repository(registry, only=repository)
	except (ValueError, RuntimeError) as exc:
	# A duplicate identifier or an unresolvable handler: both are bugs
	# in this repository rather than operator error. The worker still
	# runs everything else, and says which one it dropped, because a
	# worker that refuses every tool over one broken skill is worse.
	notes.append(f"the skill repository could not be installed ({exc})")

	accounted, mcp_notes = _install_mcp_catalogue(registry, policy, environ)
	notes.extend(mcp_notes)

	installed = frozenset(spec.ref for spec in registry.specs())
	unmatched = sorted(
	policy.approved - installed - accounted, key=lambda ref: (ref.tool_id, ref.version)
	)
	for ref in unmatched:
	# Almost always a typo. Saying so beats leaving the operator to work
	# out why a tool they approved never appears in what the worker offers.
	notes.append(
	f"{ref.tool_id}@{ref.version} is approved but nothing installs it; check the "
	"spelling against the list of approvable refs"
	)
	return registry, tuple(notes)


	def default_registry(*, environ: Mapping[str, str] \| None = None) -> Registry:
	"""Return the agent's tool registry: only what the operator approved.

	There is still no entry-point discovery, import scanning or dynamic module
	loading, and no credential-gated registration. A tool appears here only
	because a human named it in :data:`~distinct_tools.approval.APPROVED_TOOLS_ENV_VAR`
	or a policy file. With neither set, this returns an empty registry and
	every tool call fails closed.

	Three sources feed it and all three obey the same gate. The library members
	in :data:`INSTALLABLE_SPECS` are registered directly; the skills in
	:mod:`distinct_skills` are installed from their pinned directories; the MCP
	servers in :mod:`distinct_mcp` are built and installed. A server that is
	approved but cannot be built is skipped rather than fatal, and the reason
	is available from :func:`registry_notes`.

	Re-read on each call rather than cached, so an operator who changes their
	approvals does not have to restart the worker. A run already in flight is
	unaffected: :class:`ToolBroker` snapshots the registry at construction.
	Building an MCP server here is still discovery at install time in the sense
	:mod:`distinct_tools.mcp` means it: it happens before the job's broker
	exists, the broker then snapshots, and no run ever negotiates with a
	server. The servers are in-process code from this repository, so the
	listing costs no I/O beyond the file server resolving its directory.
	"""

	return _build_registry(environ)[0]


	def registry_notes(*, environ: Mapping[str, str] \| None = None) -> tuple[str, ...]:
	"""Say what the operator approved and did not get, and why.

	Empty when everything approved was installed. Anything here is a capability
	the worker is not offering despite being told to, which is a fact that has
	to reach a person: the alternatives are failing open, or a silence that
	reads as success.
	"""

	return _build_registry(environ)[1]


	def approvable_refs() -> tuple[str, ...]:
	"""Every ``id@version`` an operator could name today, from all three sources.

	Not filtered by what is approved: this is the menu, not the order. The MCP
	half is derived from the catalogue's manifests rather than by building the
	servers, so the file server appears here whether or not a directory has
	been nominated for it yet.
	"""

	refs = {f"{spec.tool_id}@{spec.version}" for spec in INSTALLABLE_SPECS}
	refs \|= {f"{spec.tool_id}@{spec.version}" for spec in REPOSITORY_SPECS}
	try:
	from distinct_mcp import catalogue_refs # deferred: see _install_mcp_catalogue
	except ImportError: # pragma: no cover - distinct_mcp is part of this repository
	return tuple(sorted(refs))
	return tuple(sorted(refs \| set(catalogue_refs())))


	def available_tool_refs(*, environ: Mapping[str, str] \| None = None) -> tuple[str, ...]:
	"""Detect approved, installed capabilities as sorted ``id@version`` refs.

	This is what the worker advertises. A tool the operator has not approved
	is never advertised, so a server cannot select it in the first place; the
	broker refuses it again if one tries anyway.
	"""

	return tuple(sorted(f"{spec.tool_id}@{spec.version}" for spec in default_registry(environ=environ).specs()))


	__all__ = [
	"APPROVED_EGRESS_ENV_VAR",
	"APPROVED_TOOLS_ENV_VAR",
	"DENY_ALL",
	"INSTALLABLE_SPECS",
	"REPOSITORY_SKILLS",
	"REPOSITORY_SPECS",
	"REPOSITORY_STATUS",
	"describe_skill_repository",
	"install_skill_repository",
	"LOCAL_BUNDLE",
	"LOCAL_SPECS",
	"POLICY_FILE_ENV_VAR",
	"JobPolicy",
	"OperatorPolicy",
	"OperatorRefusal",
	"Registry",
	"ToolBroker",
	"ToolCallError",
	"ToolCallRecord",
	"ToolContext",
	"ToolInputError",
	"ToolPolicyError",
	"ToolRef",
	"ToolResult",
	"ToolSpec",
	"ToolTrace",
	"approvable_refs",
	"available_tool_refs",
	"default_registry",
	"describe_for_agent",
	"SKILL_SPECS",
	"load_policy",
	"normalize_host",
	"operator_policy",
	"register_local_tools",
	"register_skills",
	"register_workspace_tools",
	"registry_notes",
	"WORKSPACE_SPECS",
	]