mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-19 19:00:36 +00:00
* feat(authz): add plugin resource targets, provenance, action and management enforcement
PR1 of the extension-tool-authorization series
(docs/plans/2026-09-24-extension-tool-authorization-spec.md): plugin
authorization plumbing, no new author-facing declaration.
- `authz/plugin_targets.py` is the single encoder/validator for composite
targets (`namespace/part`), with one validating composer behind three
kind-checked constructors; invalid input raises instead of degrading.
- `authz/plugin_authz.py` is the harness decision layer (`plugin_action`,
`plugin_management`, plus the batch filters the page slice will consume):
disabled is a no-op, an explicit deny raises, and provider errors follow
`fail_closed` like the sandbox gate.
- `POST /api/plugins/{ns}/actions/{name}` decides `plugin_action:invoke`
after the action resolves and before the body is streamed.
- `deerflow_extension_api.auth` publishes `require_plugin_management` /
`arequire_plugin_management` with two `app.state` resolver keys; the
Gateway installs both. Contract version 0.2.3 -> 0.2.4.
- `tools/tool_provenance.py` records host-written plugin provenance for
display (assembly descriptor, Layer-2 context later); no decision reads a
label.
- Plugin providers use a `(config signature, loop key)` cache so a
loop-affine provider is never handed to another loop or to a sync caller.
- RBAC gains `plugin_actions` / `plugin_management` aliases;
`config_version` 47 -> 48 across the three mirrors.
Tests: new plugin target/provenance/action/management suites plus a
blocking-IO anchor whose offloads were reverted to prove red->green.
* fix(authz): decide plugin resources from the request's config snapshot
Review round 1 on PR #5842 (willem-bd).
P1 — the decision layer no longer reloads the configuration. The six
`authz/plugin_authz.py` functions take a required `app_config` snapshot (the
same request-scoped config the Gateway used to resolve the provider), and
`resolve_/aresolve_plugin_authorization` return it as a third element, so
`enabled`/`fail_closed` can never come from a second read that drifted from
the one that produced the provider. A snapshot the caller could not read at
all is *unavailable*, not disabled: it fails closed as
`authz.config_unavailable`. The Gateway's `_plugin_app_config` now separates
an absent `config.yaml` (no gate, today's behavior) from a config that exists
but cannot be read or validated (deny) instead of swallowing both through
`safe_app_config`.
P2 — `_validated_decision` requires `type(decision.allow) is bool` on both
the sync `authorize` and async `aauthorize` paths, so a provider returning
`AuthzDecision(allow="false")` is a malformed verdict that follows
`fail_closed` instead of being read as an allow.
Both fixes are covered by regression tests that were verified red against the
pre-fix behavior (P1: 200 vs 403 and resolver True vs False; P2: 12 cases
across fail_closed/fail_open and sync/async), plus tests pinning that an
absent config and `authorization.enabled: false` keep today's behavior.
* fix(authz): treat a request-time config absence as unavailable
Review round 2 on PR #5842 (willem-bd).
P1 — `_plugin_app_config[_async]` no longer maps a missing `config.yaml` to
`None` ("no gate"). A Gateway cannot have started without a readable config
(`app/gateway/app.py` reads it through this same accessor in `lifespan`), so
absence *during a request* means the configuration this process was running on
became unavailable — a hot reload, an atomic replace, a ConfigMap remount. It is
unavailable, not disabled: the error propagates,
`resolve_/aresolve_plugin_authorization` raise
`_PluginAuthorizationUnavailable(fail_closed=True)`, the action dispatcher
returns 403 and the management resolvers answer `False`. The dead
`(None, None, None)` allow path is gone, the resolvers return a non-optional
`AppConfig` as their third element, and callers key "authorization disabled" on
`provider is None` alone. This matches the rule the decision layer already
documented (`authz.config_unavailable`) and the public docs.
P2 — `_deny_reason_code` is total: a `reasons` that is not iterable degrades the
code to `authz.denied` instead of raising `TypeError` outside the guarded
provider path, which turned a denial into an unhandled error. It is deliberately
not folded into `_validated_decision`: `allow` was a real `bool`, so the verdict
is a valid denial, and treating it as malformed would flip it to an allow under
`fail_closed: false`.
Both fixes are covered by regression tests verified red against the pre-fix
behavior (P1: resolver True vs False, async `PermissionError` not raised, route
200 vs 403; P2: `TypeError: 'NoneType' object is not iterable` at
`plugin_authz.py:113`). The action-route tests in
`tests/test_plugin_contributions.py` now install a readable
`authorization.enabled: false` config instead of relying on a config-less
process, and `docs/full-stack-plugins.md` plus the PR1 decision log record the
new rule.
* fix(authz): apply the running policy when the plugin config is unreadable
Follow-up to f03d2ea9 (review round 2 on PR #5842, willem-bd).
The first attempt read the P1 finding as "absence is never disabled" and failed
every config read closed unconditionally. That is too broad for this repo: a
config-less host is deliberately treated as having no policy to apply
(`_get_route_authorization_config` falls back to a disabled config,
`sandbox_authz.safe_app_config` documents the same no-op for "CI runners and
direct-call tests"), and the rule turned the config-less e2e plugin host
(`extension_test_fixtures.bookmark_plugin_gateway`) into a 403 — the three
`bookmark-plugin.spec.ts` cases lost the save action. Reproduced locally:
`POST /api/plugins/community.bookmarks/actions/save` against that fixture host
returned 403 before, 200 after this change.
The rule is now "has this process loaded a configuration?", not "was the last
read successful?":
- No loaded config (`peek_loaded_app_config()`, new read-only accessor on
`deerflow.config.app_config`) and no `config.yaml`: no policy to apply, so the
gate stays a no-op — unchanged for CI runners, direct-call tests and hosts
that mount only the plugins router.
- A loaded config whose file disappears or cannot be read: *unavailable*, never
*disabled*. The resolvers raise `_PluginAuthorizationUnavailable` carrying the
failure flag of the configuration this process runs on (authorization
disabled there -> no gate; enabled -> that policy's `fail_closed`, `True` by
default), so an enabled Gateway answers 403/False in the window instead of
letting protected plugin actions and management routes through.
- A config file that exists but cannot be read or validated right now: fail
closed when nothing is loaded (round 1's rule), otherwise the loaded policy
decides.
`peek_loaded_app_config()` is preferred over a Gateway-side startup snapshot: it
reflects the last successfully loaded config, so a hot-reloaded policy is what
applies during the window, and there is no lifecycle hook to keep in sync.
Evidence: the three no-config/lost-config branches in
`tests/test_plugin_management_guard.py` and
`tests/test_plugin_action_authorization.py`, round 1's unreadable-config tests
unchanged, `test_peek_loaded_app_config_survives_a_missing_file` in
`tests/test_app_config_reload.py`, and the fixture-host probe above. Docs
(`docs/full-stack-plugins.md`, `reference.mdx` en/zh) and the PR1 decision log
state the final rule; the log records the superseded variant.
* fix(authz): keep a denial whose reasons raise while being read
* fix(authz): intersect plugin batch filters with the candidates
The plugin_page/plugin_management batch helpers returned the provider's
`filter_resources` answer verbatim, so a custom provider could hand the
projections a target that was never asked about ("*", another namespace,
a phantom page). Every other filter call site re-projects from its own
candidate list; do the same here, state the intersection on the provider
contract, and pin it with a regression test that fails on the old
pass-through.
* docs(plugins): map a management denial to 403 in the route example
The contributed-route example called `arequire_plugin_management` and let
the documented `PermissionError` escape. The Gateway installs no
`PermissionError` handler, so a route copied from the example answered 500
on a normal policy denial instead of 403. Both example routes now translate
the denial, and the surrounding bullets say why the translation is the
route's job.
* docs(extensions): point the 0.2.4 contract row at the PR that ships it
Every other row in the version-history table links the pull request that
shipped the version; 0.2.4 linked the authorization tracking issue instead.
Both the English and Chinese tables now link this PR.
509 lines
20 KiB
Python
509 lines
20 KiB
Python
"""Projection of an assembled agent into a comparable descriptor.
|
|
|
|
The factory knows things nothing downstream can recover: which model survived
|
|
the runtime overrides, what the rendered prompt actually said, which tools
|
|
authorization left in place, and the order the middleware stack ended up in.
|
|
This module turns that transient knowledge into
|
|
:class:`~deerflow_extension_api.assembly.AgentAssemblyDescriptor`.
|
|
|
|
Two rules shape the projection:
|
|
|
|
* **Declared beats probed.** A middleware that implements
|
|
``release_policy_parameters()`` owns its own behaviour identity; probing
|
|
private attributes is the fallback for the ones that do not, and is marked as
|
|
such so a reader can tell a contract from a guess.
|
|
* **Hash, do not copy.** Prompts, tool descriptions, and argument schemas are
|
|
reduced to hashes. A descriptor is an identity, not a second copy of the
|
|
agent's payload.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
import os
|
|
from importlib.metadata import PackageNotFoundError, version
|
|
from pathlib import Path
|
|
|
|
from deerflow_extension_api import (
|
|
AgentAssemblyDescriptor,
|
|
MiddlewareDescriptor,
|
|
ToolDescriptor,
|
|
canonical_hash,
|
|
collect_release_policies,
|
|
)
|
|
|
|
from deerflow.sandbox.env_policy import is_blocked_env_name
|
|
from deerflow.tools.mcp_metadata import get_mcp_source, is_mcp_tool
|
|
from deerflow.tools.tool_provenance import resolve_tool_provenance
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
# Fields on a model profile that are pure identity/presentation metadata: they
|
|
# never reach the provider constructor (see ``create_chat_model``'s own
|
|
# exclude set) and renaming/re-describing a model must not look like a
|
|
# behaviour change. ``use`` is surfaced separately as ``provider``.
|
|
_MODEL_METADATA_FIELDS = frozenset(
|
|
{
|
|
"name",
|
|
"display_name",
|
|
"description",
|
|
"use",
|
|
"context_window",
|
|
"pricing",
|
|
# ``reasoning`` is deliberately *not* excluded: as a bool or level
|
|
# string it is ChatOllama's native provider kwarg, and as a declared
|
|
# contract its dialect/history change the request payload. Both must
|
|
# move the assembly fingerprint (issue #5073, PR #5780 review).
|
|
}
|
|
)
|
|
_MIDDLEWARE_PUBLIC_FIELDS = (
|
|
"max_concurrent",
|
|
"max_total",
|
|
"warn_threshold",
|
|
"hard_limit",
|
|
"window_size",
|
|
"max_tracked_threads",
|
|
"tool_freq_warn",
|
|
"tool_freq_hard_limit",
|
|
"trigger",
|
|
"keep",
|
|
"trim_tokens_to_summarize",
|
|
"fail_closed",
|
|
"passport",
|
|
"_tool_freq_overrides",
|
|
"_top_k",
|
|
"_deferred",
|
|
"_catalog_hash",
|
|
)
|
|
_MIDDLEWARE_HASHED_TEXT_FIELDS = (
|
|
"summary_prompt",
|
|
"system_prompt",
|
|
"tool_description",
|
|
)
|
|
_MODEL_IDENTITY_FIELDS = (
|
|
"model",
|
|
"model_name",
|
|
"deployment_name",
|
|
)
|
|
_PROVIDER_PARAMETER_FIELDS = (
|
|
"_allowed",
|
|
"_denied",
|
|
"_default_role",
|
|
"_resource_type",
|
|
"_action",
|
|
)
|
|
_DETECTOR_PARAMETER_FIELDS = (
|
|
"_finish_reasons",
|
|
"_stop_reasons",
|
|
)
|
|
|
|
|
|
def _plain_value(value: object) -> object | None:
|
|
"""Reduce ``value`` to JSON-shaped data, or ``None`` when it cannot be.
|
|
|
|
``None`` means "not describable", which is deliberately indistinguishable
|
|
from a real ``None``: both are equally uninformative for identity, and
|
|
inventing a marker would make two undescribable values look different.
|
|
"""
|
|
if value is None or isinstance(value, bool | int | float | str):
|
|
return value
|
|
if isinstance(value, (list, tuple, set, frozenset)):
|
|
children = [_plain_value(child) for child in value]
|
|
if any(child is None and original is not None for child, original in zip(children, value, strict=True)):
|
|
return None
|
|
return sorted(children, key=str) if isinstance(value, (set, frozenset)) else children
|
|
if isinstance(value, dict):
|
|
result: dict[str, object] = {}
|
|
for key, child in value.items():
|
|
if not isinstance(key, str):
|
|
continue
|
|
plain = _plain_value(child)
|
|
if plain is not None or child is None:
|
|
result[key] = plain
|
|
return result
|
|
model_dump = getattr(value, "model_dump", None)
|
|
if callable(model_dump):
|
|
try:
|
|
return _plain_value(model_dump(mode="python"))
|
|
except Exception:
|
|
return None
|
|
return None
|
|
|
|
|
|
def _stable_type_name(value: object) -> str:
|
|
value_type = type(value)
|
|
return f"{value_type.__module__}.{value_type.__qualname__}"
|
|
|
|
|
|
def describe_model_identity(value: object) -> dict[str, str]:
|
|
"""Name a chat model without serialising it.
|
|
|
|
Chat-model objects carry credentials and clients, so they are never plain
|
|
data. What identifies them for comparison is the class plus the configured
|
|
model name, unwrapped through any ``bound`` runnable wrapper the middleware
|
|
stack layered on top.
|
|
"""
|
|
original = value
|
|
if isinstance(value, str):
|
|
return {"class": "builtins.str", "name": value}
|
|
resolved = value
|
|
seen: set[int] = set()
|
|
for _ in range(8):
|
|
if not hasattr(resolved, "bound") or id(resolved) in seen:
|
|
break
|
|
seen.add(id(resolved))
|
|
bound = getattr(resolved, "bound")
|
|
if bound is None or bound is resolved:
|
|
break
|
|
resolved = bound
|
|
identity = {"class": _stable_type_name(resolved)}
|
|
for candidate in (resolved, original):
|
|
for field_name in _MODEL_IDENTITY_FIELDS:
|
|
field_value = getattr(candidate, field_name, None)
|
|
if isinstance(field_value, str) and field_value:
|
|
identity["name"] = field_value
|
|
break
|
|
if "name" in identity:
|
|
break
|
|
return identity
|
|
|
|
|
|
def _provider_identity(value: object) -> dict[str, object]:
|
|
identity: dict[str, object] = {
|
|
"class": _stable_type_name(value),
|
|
"name": str(getattr(value, "name", type(value).__name__)),
|
|
}
|
|
parameters: dict[str, object] = {}
|
|
for field_name in _PROVIDER_PARAMETER_FIELDS:
|
|
if not hasattr(value, field_name):
|
|
continue
|
|
raw_value = getattr(value, field_name)
|
|
plain = _plain_value(raw_value)
|
|
if plain is not None or raw_value is None:
|
|
parameters[field_name.removeprefix("_")] = plain
|
|
if parameters:
|
|
identity["parameters"] = parameters
|
|
nested = getattr(value, "_provider", None)
|
|
if nested is not None and nested is not value:
|
|
identity["provider"] = _provider_identity(nested)
|
|
return identity
|
|
|
|
|
|
def _tool_schema(tool: object) -> dict[str, object]:
|
|
get_input_schema = getattr(tool, "get_input_schema", None)
|
|
if callable(get_input_schema):
|
|
try:
|
|
schema_model = get_input_schema()
|
|
schema = schema_model.model_json_schema()
|
|
if isinstance(schema, dict):
|
|
return schema
|
|
except Exception:
|
|
pass
|
|
args_schema = getattr(tool, "args_schema", None)
|
|
model_json_schema = getattr(args_schema, "model_json_schema", None)
|
|
if callable(model_json_schema):
|
|
try:
|
|
schema = model_json_schema()
|
|
if isinstance(schema, dict):
|
|
return schema
|
|
except Exception:
|
|
pass
|
|
return {}
|
|
|
|
|
|
def _tool_source(tool: object) -> str:
|
|
"""Project the tool's display attribution (see `deerflow.tools.tool_provenance`).
|
|
|
|
Delegates so the descriptor identity and the execution-time label cannot
|
|
disagree. Labels for sources that carry no host-written tag are unchanged.
|
|
"""
|
|
provenance = resolve_tool_provenance(tool)
|
|
return provenance.source if provenance is not None else "builtin"
|
|
|
|
|
|
def describe_tool(tool: object) -> ToolDescriptor:
|
|
"""Project one bound tool into its identity."""
|
|
source = get_mcp_source(tool) if is_mcp_tool(tool) else None
|
|
return ToolDescriptor(
|
|
name=str(getattr(tool, "name", type(tool).__name__)),
|
|
description_hash=canonical_hash(str(getattr(tool, "description", "") or "")),
|
|
schema_hash=canonical_hash(_plain_value(_tool_schema(tool))),
|
|
source=_tool_source(tool),
|
|
mcp_server=source["server_name"] if source is not None else None,
|
|
mcp_transport=source["transport"] if source is not None else None,
|
|
)
|
|
|
|
|
|
def _probe_middleware_parameters(middleware: object) -> dict[str, object]:
|
|
"""Best-effort identity for a middleware that declares none of its own."""
|
|
parameters: dict[str, object] = {}
|
|
for field_name in _MIDDLEWARE_PUBLIC_FIELDS:
|
|
if not hasattr(middleware, field_name):
|
|
continue
|
|
raw_value = getattr(middleware, field_name)
|
|
plain = _plain_value(raw_value)
|
|
if plain is not None or raw_value is None:
|
|
parameters[field_name.removeprefix("_")] = plain
|
|
for field_name in _MIDDLEWARE_HASHED_TEXT_FIELDS:
|
|
raw_value = getattr(middleware, field_name, None)
|
|
if isinstance(raw_value, str):
|
|
parameters[f"{field_name}_hash"] = canonical_hash(raw_value)
|
|
model = getattr(middleware, "model", None)
|
|
if model is not None:
|
|
parameters["model"] = describe_model_identity(model)
|
|
provider = getattr(middleware, "provider", None)
|
|
if provider is not None:
|
|
parameters["provider"] = _provider_identity(provider)
|
|
routing_index = getattr(middleware, "_routing_index", None)
|
|
plain_routing_index = _plain_value(routing_index)
|
|
if plain_routing_index is not None:
|
|
parameters["routing_index_hash"] = canonical_hash(plain_routing_index)
|
|
detectors = getattr(middleware, "_detectors", None)
|
|
if isinstance(detectors, (list, tuple)):
|
|
detector_descriptors: list[dict[str, object]] = []
|
|
for detector in detectors:
|
|
descriptor: dict[str, object] = {
|
|
"class": _stable_type_name(detector),
|
|
"name": str(getattr(detector, "name", type(detector).__name__)),
|
|
}
|
|
detector_parameters: dict[str, object] = {}
|
|
for field_name in _DETECTOR_PARAMETER_FIELDS:
|
|
if not hasattr(detector, field_name):
|
|
continue
|
|
raw_value = getattr(detector, field_name)
|
|
plain = _plain_value(raw_value)
|
|
if plain is not None or raw_value is None:
|
|
detector_parameters[field_name.removeprefix("_")] = plain
|
|
if detector_parameters:
|
|
descriptor["parameters"] = detector_parameters
|
|
detector_descriptors.append(descriptor)
|
|
parameters["detectors"] = detector_descriptors
|
|
config = getattr(middleware, "_config", None)
|
|
plain_config = _plain_value(config)
|
|
if isinstance(plain_config, dict):
|
|
parameters["config"] = plain_config
|
|
return parameters
|
|
|
|
|
|
def _unwrap_middleware(middleware: object) -> tuple[object, str | None]:
|
|
"""Return the middleware that owns the behaviour, plus its extension.
|
|
|
|
Extension contributions reach the stack inside an isolation wrapper whose
|
|
dynamically generated subclass is named after the wrapper, not the
|
|
contribution — so every contributed middleware in the process shares one
|
|
class name and one (empty) probe result. Describing the wrapper would
|
|
collapse them all into a single indistinguishable descriptor and hide any
|
|
policy change inside them.
|
|
|
|
Duck-typed on ``inner``/``source`` rather than importing the wrapper type:
|
|
``deerflow.extensions`` sits below this layer, so importing it here would
|
|
point the dependency backwards, and any future wrapper of the same shape
|
|
is handled for free.
|
|
"""
|
|
described = middleware
|
|
extension: str | None = None
|
|
for _ in range(4):
|
|
inner = getattr(described, "inner", None)
|
|
if inner is None or inner is described:
|
|
break
|
|
source = getattr(described, "source", None)
|
|
if not isinstance(source, str) or not source:
|
|
source = getattr(described, "name", None)
|
|
if isinstance(source, str) and source and extension is None:
|
|
extension = source
|
|
described = inner
|
|
return described, extension
|
|
|
|
|
|
def describe_middleware(middleware: object) -> MiddlewareDescriptor:
|
|
"""Project one middleware, preferring its own declaration over probing."""
|
|
described, extension = _unwrap_middleware(middleware)
|
|
name = type(described).__name__
|
|
declared = collect_release_policies([described])
|
|
if name in declared:
|
|
parameters = _plain_value(declared[name])
|
|
if not isinstance(parameters, dict):
|
|
logger.warning("%s declared a release policy that is not plain data; recording it as unserialisable", name)
|
|
parameters = {"error": "UnserialisableDeclaration"}
|
|
else:
|
|
parameters = {"probed": True, **_probe_middleware_parameters(described)}
|
|
return MiddlewareDescriptor(
|
|
name=name,
|
|
module=type(described).__module__,
|
|
policy_parameters=parameters,
|
|
extension=extension,
|
|
)
|
|
|
|
|
|
def _build_identity() -> dict[str, str]:
|
|
"""Which build produced this assembly, when the deployment says so.
|
|
|
|
Reported on its own descriptor field rather than inside
|
|
``effective_policies`` because the latter is hashed into the fingerprint:
|
|
a redeploy that changes nothing about an agent must not change that
|
|
agent's fingerprint.
|
|
"""
|
|
try:
|
|
package_version = version("deerflow-harness")
|
|
except PackageNotFoundError:
|
|
package_version = "unknown"
|
|
return {
|
|
"package_version": package_version,
|
|
"image_digest": os.environ.get("DEER_FLOW_IMAGE_DIGEST", "unknown"),
|
|
"git_commit": os.environ.get("DEER_FLOW_GIT_COMMIT", "unknown"),
|
|
}
|
|
|
|
|
|
def _effective_model_fields(model_config: object) -> dict[str, object]:
|
|
"""All fields the model profile actually carries, declared or extra.
|
|
|
|
``ModelConfig`` is ``extra="allow"``, so a provider kwarg a user sets
|
|
(``temperature``, ``max_tokens``, anything else) lives only as an extra
|
|
field — a fixed allowlist would never see it. ``model_dump`` is the
|
|
profile's own account of its fields, extras included, so it is preferred
|
|
over probing named attributes. Falls back to plain instance attributes
|
|
for a non-pydantic profile (e.g. the ``SimpleNamespace`` a subagent
|
|
builds when its model name has no entry in the config table).
|
|
"""
|
|
model_dump = getattr(model_config, "model_dump", None)
|
|
if callable(model_dump):
|
|
try:
|
|
dumped = model_dump(mode="python")
|
|
except Exception:
|
|
dumped = None
|
|
if isinstance(dumped, dict):
|
|
return dumped
|
|
namespace = getattr(model_config, "__dict__", None)
|
|
return dict(namespace) if isinstance(namespace, dict) else {}
|
|
|
|
|
|
def _model_parameters(model_config: object, model_overrides: dict[str, object] | None = None) -> dict[str, object]:
|
|
"""The behaviour-affecting half of a model profile, as actually constructed.
|
|
|
|
Built from the profile's own effective fields plus any per-caller
|
|
overrides actually applied on top (e.g. a custom agent's ``model_settings``
|
|
sampling overrides, or a request's runtime overrides) — mirroring what
|
|
``create_chat_model`` layers onto the constructor — rather than a fixed
|
|
allowlist, so a changed ``temperature``/``max_tokens``/arbitrary provider
|
|
kwarg is always visible here.
|
|
|
|
Credential-shaped field names (``api_key`` and anything else
|
|
``is_blocked_env_name`` flags) are never projected, and values that
|
|
cannot be reduced to plain JSON-shaped data are silently dropped rather
|
|
than raising (see ``_plain_value``).
|
|
|
|
``thinking_enabled`` and ``reasoning_effort`` are descriptor fields in their
|
|
own right, so they are deliberately not duplicated here.
|
|
"""
|
|
use = getattr(model_config, "use", None)
|
|
result: dict[str, object] = {"provider": str(use) if use else None}
|
|
effective = _effective_model_fields(model_config)
|
|
if model_overrides:
|
|
effective = {**effective, **{key: value for key, value in model_overrides.items() if value is not None}}
|
|
for field_name, value in effective.items():
|
|
if not isinstance(field_name, str) or field_name in _MODEL_METADATA_FIELDS:
|
|
continue
|
|
if is_blocked_env_name(field_name):
|
|
continue
|
|
plain = _plain_value(value)
|
|
if plain is not None or value is None:
|
|
result[field_name] = plain
|
|
return result
|
|
|
|
|
|
def _skill_content_hash(skill: object) -> str | None:
|
|
"""Digest of a skill's ``SKILL.md`` body.
|
|
|
|
``SkillActivationMiddleware`` injects this body as current-turn context
|
|
(see ``skill_activation_middleware._read_skill_content``), so it is what
|
|
actually drives the agent's behaviour when the skill is used — not just
|
|
the name/description/allowed-tools already projected above. ``Skill``
|
|
does not cache its content as a field (the middleware re-reads it from
|
|
disk at activation time), so this does the same rather than inventing a
|
|
cached-content field the rest of the system does not have. A skill whose
|
|
file has gone missing or become unreadable is recorded as undescribable
|
|
(``None``) rather than raising — assembly must not fail because a skill
|
|
file disappeared out from under it.
|
|
"""
|
|
skill_file = getattr(skill, "skill_file", None)
|
|
if not isinstance(skill_file, Path):
|
|
return None
|
|
try:
|
|
content = skill_file.read_text(encoding="utf-8")
|
|
except OSError:
|
|
return None
|
|
return canonical_hash(content)
|
|
|
|
|
|
def build_assembly_descriptor(
|
|
*,
|
|
namespace: str,
|
|
agent_name: str,
|
|
requested_model: str | None,
|
|
effective_model: str,
|
|
model_config: object,
|
|
model_overrides: dict[str, object] | None = None,
|
|
thinking_enabled: bool,
|
|
reasoning_effort: object,
|
|
rendered_base_prompt: str,
|
|
prompt_template_id: str = "deerflow-lead-agent-v1",
|
|
tools: list[object],
|
|
middlewares: list[object],
|
|
deferred_names: frozenset[str],
|
|
enabled_skills: list[object],
|
|
effective_policies: dict[str, object],
|
|
) -> AgentAssemblyDescriptor:
|
|
"""Describe one finished assembly.
|
|
|
|
``tools`` is the list bound to the graph; middleware-owned tools are folded
|
|
in because the model sees them exactly the same way. The skill catalog is
|
|
hashed rather than listed field-by-field so editing a skill's body changes
|
|
the fingerprint while the descriptor stays small.
|
|
"""
|
|
skill_catalog = [
|
|
{
|
|
"name": str(getattr(skill, "name", "")),
|
|
"description": str(getattr(skill, "description", "")),
|
|
# None preserves legacy allow-all; an empty declaration allows no business tools.
|
|
"allowed_tools": None if (allowed_tools := getattr(skill, "allowed_tools", None)) is None else sorted(str(item) for item in allowed_tools),
|
|
"content_hash": _skill_content_hash(skill),
|
|
"secrets_autonomous": bool(getattr(skill, "secrets_autonomous", True)),
|
|
"required_secrets": sorted(f"{getattr(requirement, 'name', '')}:{bool(getattr(requirement, 'optional', False))}" for requirement in (getattr(skill, "required_secrets", None) or ())),
|
|
}
|
|
for skill in enabled_skills
|
|
]
|
|
assembled_tools = list(tools)
|
|
for middleware in middlewares:
|
|
middleware_tools = getattr(middleware, "tools", None)
|
|
if isinstance(middleware_tools, (list, tuple)):
|
|
assembled_tools.extend(middleware_tools)
|
|
|
|
resolved_policies = dict(effective_policies)
|
|
resolved_policies["prompt_template_id"] = prompt_template_id
|
|
resolved_policies["skill_catalog_hash"] = canonical_hash(sorted(skill_catalog, key=lambda item: item["name"]))
|
|
|
|
return AgentAssemblyDescriptor(
|
|
namespace=namespace,
|
|
agent_name=agent_name,
|
|
requested_model=requested_model,
|
|
effective_model=effective_model,
|
|
model_parameters=_model_parameters(model_config, model_overrides),
|
|
thinking_enabled=thinking_enabled,
|
|
reasoning_effort=_plain_value(reasoning_effort),
|
|
base_prompt_hash=canonical_hash(rendered_base_prompt),
|
|
tools=tuple(describe_tool(tool) for tool in assembled_tools),
|
|
middlewares=tuple(describe_middleware(middleware) for middleware in middlewares),
|
|
deferred_tool_names=tuple(sorted(str(name) for name in deferred_names)),
|
|
enabled_skills=tuple(entry["name"] for entry in skill_catalog),
|
|
effective_policies=resolved_policies,
|
|
build=_build_identity(),
|
|
)
|
|
|
|
|
|
__all__ = [
|
|
"build_assembly_descriptor",
|
|
"describe_middleware",
|
|
"describe_model_identity",
|
|
"describe_tool",
|
|
]
|