Governance & Engine¶
Governance covers permission policy, OS sandboxing, audit logging, event hooks, and scheduled tasks. The engine layer is the turn execution kernel: model invocation, tool coordination, prompt assembly, acceptance gates, and deliverable collection.
See Security, Platform & MCP and
Subagents, Hooks & Memory for the
user-facing flows (permissions.toml, hooks.toml, /cron, /rule).
Permissions¶
PermissionPolicy
dataclass
¶
PermissionPolicy(
tool_rules: dict[str, str] = dict(),
command_rules: dict[str, str] = dict(),
)
Per-tool and per-domain permission rules.
Rules are checked before the interactive prompt. For command rules the
most specific (longest) matching prefix wins, so a narrow deny
always overrides a broad allow. If no rule matches, the normal
PermissionLevel flow applies.
tool_rules
class-attribute
instance-attribute
¶
tool_rules: dict[str, str] = field(default_factory=dict)
command_rules
class-attribute
instance-attribute
¶
command_rules: dict[str, str] = field(default_factory=dict)
check_tool
¶
check_tool(tool_name: str) -> str | None
Return the policy decision for a tool, or None to fall through.
Source code in src/dashscope_agenticx/permission.py
54 55 56 | |
check_command
¶
check_command(command: str) -> str | None
Return the policy decision for a shell command, or None.
Source code in src/dashscope_agenticx/permission.py
58 59 60 61 62 63 64 65 66 67 | |
add_tool_rule
¶
add_tool_rule(tool_name: str, decision: str) -> None
Source code in src/dashscope_agenticx/permission.py
69 70 71 72 73 74 | |
add_command_rule
¶
add_command_rule(prefix: str, decision: str) -> None
Source code in src/dashscope_agenticx/permission.py
76 77 78 79 80 81 82 83 84 | |
load_permission_policy
¶
load_permission_policy(
policy: PermissionPolicy | None = None,
) -> PermissionPolicy
Load configured rules without modifying the process-wide facade.
Source code in src/dashscope_agenticx/permission.py
154 155 156 157 158 159 160 161 162 163 164 165 166 167 | |
load_permissions_file
¶
load_permissions_file(
policy: PermissionPolicy, path: Path
) -> list[str]
Merge a permissions.toml into policy; returns load errors.
Source code in src/dashscope_agenticx/permission.py
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 | |
get_permission_policy
¶
get_permission_policy() -> PermissionPolicy
Source code in src/dashscope_agenticx/permission.py
131 132 133 | |
set_permission_policy
¶
set_permission_policy(policy: PermissionPolicy) -> None
Source code in src/dashscope_agenticx/permission.py
136 137 138 | |
configure_permission_policy
¶
configure_permission_policy() -> PermissionPolicy
Load permissions.toml (global + workspace) into the global policy.
Called once at startup alongside configure_audit_logger. Workspace
rules are applied last and win on identical keys. Invalid entries are
skipped with a warning — a malformed rule must never widen permissions
silently, so bad decisions are dropped, not defaulted to allow.
Source code in src/dashscope_agenticx/permission.py
141 142 143 144 145 146 147 148 149 150 151 | |
Sandbox¶
detect_backend
¶
detect_backend() -> Optional[str]
Return the available sandbox backend name, or None.
macOS prefers sandbox-exec (Seatbelt); Linux prefers bwrap.
Windows has no supported backend. Detection only checks for the tool's
presence on PATH — it never starts a sandbox.
Source code in src/dashscope_agenticx/sandbox.py
44 45 46 47 48 49 50 51 52 53 54 55 | |
available
¶
available() -> bool
True when a sandbox backend is detected on this machine.
Source code in src/dashscope_agenticx/sandbox.py
58 59 60 | |
is_enabled
¶
is_enabled() -> bool
Whether sandboxing is enabled (config-driven, overridable).
Reads sandbox from the loaded config on each call so config
changes take effect; degrades to False on any error so the
sandbox can never break command execution.
Source code in src/dashscope_agenticx/sandbox.py
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 | |
set_enabled
¶
set_enabled(value: Optional[bool]) -> None
Override sandbox enablement; pass None to use the config value.
Source code in src/dashscope_agenticx/sandbox.py
68 69 70 71 | |
build_argv
¶
build_argv(
command: str, cwd: str, backend: Optional[str] = None
) -> Optional[list[str]]
Return an argv to run command inside the sandbox, or None.
None means "no sandbox available — run the command normally".
backend may be passed explicitly (mainly for tests); otherwise it
is detected.
Source code in src/dashscope_agenticx/sandbox.py
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 | |
seatbelt_profile
¶
seatbelt_profile(cwd: str) -> str
Build a macOS Seatbelt profile confining writes to the workspace.
The base policy stays default-allow; only filesystem writes are denied, then re-allowed for the workspace and standard temp/cache locations. Reads, process execution, and networking are untouched so ordinary development commands keep working.
Source code in src/dashscope_agenticx/sandbox.py
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 | |
bwrap_argv
¶
bwrap_argv(command: str, cwd: str) -> list[str]
Build a bwrap argv that runs command with a read-only root.
The whole filesystem is bound read-only, then the workspace and a
fresh /tmp are made writable. Commands that need to write elsewhere
(e.g. package caches) will fail — this is the intended confinement.
Source code in src/dashscope_agenticx/sandbox.py
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | |
is_sandboxed_path
¶
is_sandboxed_path(path: str, cwd: str) -> bool
True when path is inside the writable workspace or temp areas.
Informational helper (e.g. for messages); not a security check.
Source code in src/dashscope_agenticx/sandbox.py
169 170 171 172 173 174 175 176 177 178 179 180 181 | |
Audit¶
AuditEvent
dataclass
¶
AuditEvent(
timestamp: str,
source: str,
action: str,
subject: str,
decision: str,
reason: str = "",
details: dict[str, Any] = dict(),
)
One auditable action in the system.
now
classmethod
¶
now(
source: str,
action: str,
subject: str,
decision: str,
reason: str = "",
**details
) -> "AuditEvent"
Source code in src/dashscope_agenticx/audit.py
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 | |
AuditLogger
¶
AuditLogger(path: Path | None = None)
Append-only JSONL audit log.
Source code in src/dashscope_agenticx/audit.py
117 118 119 | |
set_privacy_mode
¶
set_privacy_mode(enabled: bool) -> None
Source code in src/dashscope_agenticx/audit.py
121 122 | |
log
¶
log(event: AuditEvent) -> None
Append one event. Swallows I/O errors so audit never breaks the agent.
Source code in src/dashscope_agenticx/audit.py
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | |
log_user_input
¶
log_user_input(text: str, preview_len: int = 100) -> None
Source code in src/dashscope_agenticx/audit.py
141 142 143 | |
log_tool_call
¶
log_tool_call(
tool_name: str,
args: dict[str, Any],
decision: str,
reason: str = "",
) -> None
Source code in src/dashscope_agenticx/audit.py
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | |
log_cron
¶
log_cron(
job_id: str, decision: str, reason: str = ""
) -> None
Source code in src/dashscope_agenticx/audit.py
163 164 | |
query
¶
query(
source: str | None = None,
action: str | None = None,
subject: str | None = None,
decision: str | None = None,
limit: int = 50,
) -> list[dict[str, Any]]
Read back events matching the given filters.
Source code in src/dashscope_agenticx/audit.py
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 | |
recent
¶
recent(limit: int = 20) -> list[dict[str, Any]]
Return the last N events (tail of the log).
Source code in src/dashscope_agenticx/audit.py
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 | |
clear
¶
clear() -> None
Source code in src/dashscope_agenticx/audit.py
222 223 224 225 226 | |
get_audit_logger
¶
get_audit_logger() -> AuditLogger
Source code in src/dashscope_agenticx/audit.py
234 235 | |
configure_audit_logger
¶
configure_audit_logger(config) -> AuditLogger
Wire config settings into the global audit logger at startup.
Re-arms privacy redaction after a restart: the logger is constructed at
import time with privacy off, so without this the persisted
privacy_mode = true would not redact until the user re-ran
/privacy on.
Source code in src/dashscope_agenticx/audit.py
243 244 245 246 247 248 249 250 251 252 | |
Hooks¶
Hook
¶
Hook(event: str, spec: dict[str, Any])
A single hook rule loaded from hooks.toml.
category distinguishes governance hooks (block/confirm/alert —
security-critical, permission/audit/compliance) from plugin hooks
(run/warn/log — functional extensions like tool before/after processing).
Governance hooks are dispatched first so security decisions take
precedence over functional extensions.
Source code in src/dashscope_agenticx/hooks.py
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 | |
category
instance-attribute
¶
category = (
"governance"
if self.action in self._GOVERNANCE_ACTIONS
else "plugin"
)
applies_to
¶
applies_to(ctx: HookContext) -> bool
Source code in src/dashscope_agenticx/hooks.py
335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 | |
execute
¶
execute(ctx: HookContext) -> HookActionResult
Source code in src/dashscope_agenticx/hooks.py
440 441 442 443 444 445 446 447 448 449 450 451 452 453 | |
execute_async
async
¶
execute_async(ctx: HookContext) -> HookActionResult
Async variant of execute: run-actions await an asyncio subprocess instead of blocking the event loop for up to the hook timeout.
Source code in src/dashscope_agenticx/hooks.py
455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 | |
HookBus
¶
HookBus(hooks_file: Path | None = None)
Central event bus for hooks.
Source code in src/dashscope_agenticx/hooks.py
476 477 478 | |
register
¶
register(hook: Hook) -> None
Source code in src/dashscope_agenticx/hooks.py
492 493 | |
unregister
¶
unregister(hook: Hook) -> None
Remove a previously registered hook (by identity).
Source code in src/dashscope_agenticx/hooks.py
495 496 497 | |
dispatch
¶
dispatch(ctx: HookContext) -> HookDispatchResult
Source code in src/dashscope_agenticx/hooks.py
499 500 501 502 503 504 505 506 507 508 509 510 511 | |
dispatch_async
async
¶
dispatch_async(ctx: HookContext) -> HookDispatchResult
Async variant of dispatch — identical ordering/semantics, but command hooks run as awaited asyncio subprocesses so the event loop is not blocked.
Source code in src/dashscope_agenticx/hooks.py
513 514 515 516 517 518 519 520 521 522 523 524 525 | |
HookContext
dataclass
¶
HookContext(
event: str,
tool_name: str,
arguments: dict[str, Any] = dict(),
result: str | None = None,
success: bool | None = None,
)
Context passed to every hook callback.
arguments
class-attribute
instance-attribute
¶
arguments: dict[str, Any] = field(default_factory=dict)
HookActionResult
dataclass
¶
HookActionResult(
blocked: bool = False,
confirm: bool = False,
warning: str = "",
alert: str = "",
log: str = "",
output: str = "",
error: str = "",
)
Result of a single hook action.
HookDispatchResult
dataclass
¶
HookDispatchResult(
blocked: bool = False,
confirm: bool = False,
warnings: list[str] = list(),
alerts: list[str] = list(),
logs: list[str] = list(),
outputs: list[str] = list(),
)
Aggregated result of dispatching an event to all matching hooks.
merge
¶
merge(action: HookActionResult) -> None
Source code in src/dashscope_agenticx/hooks.py
70 71 72 73 74 75 76 77 78 79 80 | |
create_hook_bus
¶
create_hook_bus(hooks_file: Path | None = None) -> HookBus
Source code in src/dashscope_agenticx/hooks.py
528 529 | |
Scheduling¶
Scheduler
¶
Scheduler(config, agent)
Source code in src/dashscope_agenticx/scheduler.py
292 293 294 295 296 297 | |
load_and_start
async
¶
load_and_start() -> None
Source code in src/dashscope_agenticx/scheduler.py
299 300 301 302 303 304 305 306 307 308 309 310 | |
shutdown
async
¶
shutdown() -> None
Source code in src/dashscope_agenticx/scheduler.py
312 313 314 315 316 317 | |
add_job
¶
add_job(
schedule: ScheduleSpec,
skills: list[SkillInvocation],
condition: str | None,
subagent: bool,
) -> CronJob
Source code in src/dashscope_agenticx/scheduler.py
319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 | |
remove_job
¶
remove_job(job_id: str) -> bool
Source code in src/dashscope_agenticx/scheduler.py
340 341 342 343 344 345 346 347 348 | |
pause_job
¶
pause_job(job_id: str) -> bool
Source code in src/dashscope_agenticx/scheduler.py
350 351 352 353 354 355 356 357 358 | |
resume_job
¶
resume_job(job_id: str) -> bool
Source code in src/dashscope_agenticx/scheduler.py
360 361 362 363 364 365 366 | |
get_pending_prompts
¶
get_pending_prompts() -> list[str]
Source code in src/dashscope_agenticx/scheduler.py
368 369 370 371 | |
print_jobs
¶
print_jobs() -> None
Source code in src/dashscope_agenticx/scheduler.py
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 | |
CronJob
dataclass
¶
CronJob(
id: str,
schedule: ScheduleSpec,
skills: list[SkillInvocation],
condition: str | None = None,
subagent: bool = True,
enabled: bool = True,
created_at: str = "",
last_run: str | None = None,
last_result: str | None = None,
run_count: int = 0,
)
to_dict
¶
to_dict() -> dict
Source code in src/dashscope_agenticx/scheduler.py
90 91 92 93 94 95 96 97 98 99 100 101 102 | |
from_dict
classmethod
¶
from_dict(d: dict) -> CronJob
Source code in src/dashscope_agenticx/scheduler.py
104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
ScheduleSpec
dataclass
¶
ScheduleSpec(
kind: str,
raw: str,
interval_seconds: float | None = None,
at_datetime: str | None = None,
cron_fields: list[str] | None = None,
)
to_dict
¶
to_dict() -> dict
Source code in src/dashscope_agenticx/scheduler.py
57 58 59 60 61 62 63 64 | |
from_dict
classmethod
¶
from_dict(d: dict) -> ScheduleSpec
Source code in src/dashscope_agenticx/scheduler.py
66 67 68 69 70 71 72 73 74 | |
SkillInvocation
dataclass
¶
SkillInvocation(name: str, args: list[str] = list())
to_dict
¶
to_dict() -> dict
Source code in src/dashscope_agenticx/scheduler.py
41 42 | |
from_dict
classmethod
¶
from_dict(d: dict) -> SkillInvocation
Source code in src/dashscope_agenticx/scheduler.py
44 45 46 | |
parse_cron_add
¶
parse_cron_add(
args_str: str,
) -> tuple[
ScheduleSpec, list[SkillInvocation], str | None, bool
]
Source code in src/dashscope_agenticx/scheduler.py
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 | |
next_cron_fire
¶
next_cron_fire(
fields: list[str], after: datetime
) -> datetime | None
Source code in src/dashscope_agenticx/scheduler.py
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 | |
Execution kernel¶
ModelInvoker
¶
Own provider streaming, retry, usage, and LLM trace bookkeeping.
invoke
async
¶
invoke(
agent: Any,
request_messages: list[dict],
tools_schema: list[dict],
*,
hint: str = "",
hint_chars: dict[str, int] | None = None
) -> AsyncIterator[ModelDelta | ModelInvocation]
Source code in src/dashscope_agenticx/engine.py
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 | |
RunGuards
¶
RunGuards()
Build volatile loop hints and enforce non-provider run limits.
Source code in src/dashscope_agenticx/engine.py
226 227 228 | |
bind
¶
bind(reflection, stagnation) -> None
Own the per-run guard trackers exposed by compatibility memory.
Source code in src/dashscope_agenticx/engine.py
230 231 232 233 | |
build_hint
¶
build_hint(
agent: Any, loop_index: int
) -> tuple[str, dict[str, int]]
Source code in src/dashscope_agenticx/engine.py
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 | |
readonly_stop
¶
readonly_stop(agent: Any) -> str
Source code in src/dashscope_agenticx/engine.py
253 254 255 256 257 258 259 260 261 262 263 264 265 | |
ToolCoordinator
¶
Coordinate calls while preserving assistant/tool message pairing.
execute
async
¶
execute(
agent: Any,
tool_calls: list[ToolCall],
messages_with_system: list[dict],
) -> ToolBatchResult
Source code in src/dashscope_agenticx/engine.py
279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 | |
SessionPersistence
¶
Commit completed turn projections, memory, and learned experience.
finalize
async
¶
finalize(
agent: Any, user_input: Any, last_content: str
) -> None
Source code in src/dashscope_agenticx/engine.py
378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 | |
Executor
¶
Executor(
auto_approve: bool = False, confirm_mode: str = "all"
)
Source code in src/dashscope_agenticx/executor.py
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 | |
fork_for_child
¶
fork_for_child() -> 'Executor'
Keep child authorization caches separate from the parent turn.
Source code in src/dashscope_agenticx/executor.py
244 245 246 247 248 249 250 251 252 | |
absorb_child_usage
¶
absorb_child_usage(child: 'Executor') -> None
Account for child work exactly once without importing its grants.
Source code in src/dashscope_agenticx/executor.py
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 | |
clear_session_trust
¶
clear_session_trust() -> None
Called by Agent at the end of each turn to reset trust grants.
Source code in src/dashscope_agenticx/executor.py
287 288 289 290 291 | |
set_permission_observer
¶
set_permission_observer(
observer: Callable[[str, dict], None] | None,
) -> None
Receive permission lifecycle metadata for typed runtime events.
Source code in src/dashscope_agenticx/executor.py
293 294 295 296 297 298 | |
trust_snapshot
¶
trust_snapshot() -> tuple[set[str], set[str], set[str]]
Turn-scoped grants as (tools allowed, commands allowed, denied).
Copies, so the /trust handlers can read and report without
holding a reference they could mutate behind the executor's back.
Source code in src/dashscope_agenticx/executor.py
310 311 312 313 314 315 316 317 318 319 320 | |
trust_tool
¶
trust_tool(name: str) -> None
Pre-approve a whole tool for this turn. Additive only.
Source code in src/dashscope_agenticx/executor.py
322 323 324 325 | |
deny_tool
¶
deny_tool(name: str) -> None
Pre-deny a whole tool for this turn. Additive only.
Source code in src/dashscope_agenticx/executor.py
327 328 329 330 | |
record_api_call
¶
record_api_call(usage: dict | None = None) -> None
Record an API call and its token usage.
Source code in src/dashscope_agenticx/executor.py
362 363 364 365 366 367 368 369 370 | |
record_error
¶
record_error() -> None
Record an error occurrence.
Source code in src/dashscope_agenticx/executor.py
372 373 374 | |
record_skills
¶
record_skills(names: list[str]) -> None
Record skill packages activated for a turn.
Source code in src/dashscope_agenticx/executor.py
376 377 378 379 380 | |
record_prompt_composition
¶
record_prompt_composition(
messages: list[dict],
tools_schema: list[dict] | None = None,
) -> dict[str, int]
Accumulate prompt size (chars) by category for one LLM call.
Also returns the per-call breakdown so the trace can persist what this specific request was made of; the accumulator feeding /stats keeps its coarser system/user/assistant/tools buckets.
Source code in src/dashscope_agenticx/executor.py
382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 | |
execute
async
¶
execute(tool_def: ToolDefinition, arguments: dict) -> str
Run one tool call and return its text result.
Thin wrapper over :meth:execute_detailed for callers that only need
the text, such as the MCP server bridge.
Source code in src/dashscope_agenticx/executor.py
429 430 431 432 433 434 435 436 | |
execute_detailed
async
¶
execute_detailed(
tool_def: ToolDefinition, arguments: dict
) -> ToolOutcome
Run one tool call and return a structured outcome.
Source code in src/dashscope_agenticx/executor.py
438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 | |
get_stats
¶
get_stats() -> dict
Return session usage statistics.
Source code in src/dashscope_agenticx/executor.py
551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 | |
ToolOutcome
dataclass
¶
ToolOutcome(
ok: bool,
text: str,
signal_kind: str,
exit_code: int | None = None,
)
Structured result of one tool call.
Reflection, experience memory, directive learning and stagnation detection all key off tool success, so this is the single source of truth for that verdict instead of each call site sniffing prefixes off the text.
cancelled
property
¶
cancelled: bool
User rejection is neutral, not a failure.
Callers must not feed it to the consecutive-failure counter, or declining a permission prompt would look like the tool breaking.
classify_tool_text
¶
classify_tool_text(
text: str, arguments: dict | None = None
) -> ToolOutcome
Derive an outcome from a tool's returned text.
Tools still signal failure by returning a string, so this remains inference — but it now happens once, here, instead of being re-guessed at every call site. The shell exit-code trailer is read as the real signal it is rather than being flattened into prose.
Source code in src/dashscope_agenticx/executor.py
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 | |
PromptContext
dataclass
¶
PromptContext(
user_input: str,
user_name: str = "",
provider_name: str = "",
model_name: str = "",
memory_manager: Any = None,
experience_tracker: Any = None,
disabled_caps_provider: Callable[[], str] | None = None,
directives_provider: (
Callable[[], list[str]] | None
) = None,
scene_provider: Callable[[], str] | None = None,
current_turn_tools: list[str] = list(),
connected_mcp_services: (
Callable[[], list[str]] | None
) = None,
)
Per-turn context handed to every section's render call.
disabled_caps_provider
class-attribute
instance-attribute
¶
disabled_caps_provider: Callable[[], str] | None = None
directives_provider
class-attribute
instance-attribute
¶
directives_provider: Callable[[], list[str]] | None = None
current_turn_tools
class-attribute
instance-attribute
¶
current_turn_tools: list[str] = field(default_factory=list)
connected_mcp_services
class-attribute
instance-attribute
¶
connected_mcp_services: Callable[[], list[str]] | None = (
None
)
default_pipeline
¶
default_pipeline(
base_prompt: str,
project_instructions: str | None,
skills_summary_fn: Callable[[list[str]], str],
active_prompts_fn: Callable[[str], str],
) -> PromptPipeline
Build the standard pipeline matching the legacy Agent section order.
Skills/skill-packages lead the ephemeral suffix (they vary with MCP state and user input); the stable prefix is only base prompt + project instructions, byte-identical across turns for provider prompt caching.
Source code in src/dashscope_agenticx/prompt_pipeline.py
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 | |
AcceptanceGate
¶
AcceptanceGate(
command: str = "",
source: str = EXPLICIT,
retries: int = DEFAULT_RETRIES,
timeout: int = DEFAULT_TIMEOUT,
)
Runs the acceptance check and decides whether the answer stands.
Two runs per turn at most: a baseline captured before the first mutation, and the check at the loop's exit. The baseline is what turns "the suite is red" into "you made it red" — Agentless reproduces the issue on the unpatched repository for the same reason, and AlphaCodium's test anchors are the same obligation stated positively.
Source code in src/dashscope_agenticx/acceptance.py
156 157 158 159 160 161 162 163 164 165 166 167 168 169 | |
from_env
classmethod
¶
from_env(oneshot: bool) -> AcceptanceGate
Build the gate from AGENTICX_ACCEPTANCE* environment
variables.
An explicit command wins over discovery. Setting
AGENTICX_ACCEPTANCE=0
turns the gate off, which is what a benchmark measuring raw model
output wants.
Source code in src/dashscope_agenticx/acceptance.py
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 | |
reset
¶
reset() -> None
Drop the previous turn's anchor and retry budget.
The baseline has to come from the workspace as this turn found it,
and the retry budget is per-turn so one slow turn cannot spend the
next one's. An in-flight capture is cancelled for the same reason:
left running, it would write the previous turn's verdict into this
turn's baseline.
Source code in src/dashscope_agenticx/acceptance.py
200 201 202 203 204 205 206 207 208 209 210 211 212 213 | |
ensure_baseline
async
¶
ensure_baseline() -> None
Capture the pre-change verdict, once per turn.
Called before the first mutating tool call rather than at turn start: a read-only or pure-answer turn never pays for a test suite, and the baseline still comes from a workspace the agent has not touched.
Concurrent callers share one task rather than checking a flag. The flag form lets the second mutating call in a parallel batch proceed while the baseline is still running, so the "pre-change" verdict would be captured against a workspace that had already changed.
Source code in src/dashscope_agenticx/acceptance.py
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 | |
check
async
¶
check() -> GateVerdict | None
Run the check at the loop's exit and rule on the answer.
None means "not applicable" — gate off, no command found, or
nothing was mutated this turn, in which case there is no work to
accept.
Source code in src/dashscope_agenticx/acceptance.py
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 | |
GateVerdict
dataclass
¶
GateVerdict(
run: AcceptanceRun, rejection: str = "", note: str = ""
)
What the loop should do about a check that did not pass.
At most one of rejection and note is non-empty. rejection
withholds the answer and sends the model back with the raw output;
note is appended to the final answer when sending it back would not
help.
discover_acceptance_command
¶
discover_acceptance_command(
cwd: str | PathLike[str] | None = None,
) -> str | None
The conventional test entry point for the project at cwd, if any.
The allowlist is deliberately short. Every entry runs code from the
repository — conftest.py at collection time, build.rs, TestMain
— so "conservative" here means "a standard test entry point for an
ecosystem whose manifest is sitting right here", not "harmless".
npm test and make test are excluded because their bodies are
arbitrary user scripts with no conventional meaning; declaring them via
AGENTICX_ACCEPTANCE_CMD is how you ask for those.
Source code in src/dashscope_agenticx/acceptance.py
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
collect_deliverables
¶
collect_deliverables(messages: list[dict]) -> list[Path]
Scan tool messages and return existing file paths produced this turn.
Source code in src/dashscope_agenticx/deliverable.py
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 | |
surface_deliverables
¶
surface_deliverables(
deliverables: list[Path], auto_open: bool = False
) -> None
Print a summary of generated files and optionally open them.
Source code in src/dashscope_agenticx/deliverable.py
137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 | |
Subagents & delegation¶
SubagentDef
dataclass
¶
SubagentDef(
key: str,
name: str,
description: str,
source: str,
category: str,
enabled: bool,
)
discover_subagents
¶
discover_subagents(config: Config) -> list[SubagentDef]
Scan capabilities to find subagent-type ones.
Source code in src/dashscope_agenticx/agents/subagents.py
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | |
bind_subagent_context
¶
bind_subagent_context(agent, config)
Bind parent/config for one runtime context without global overwrite.
Source code in src/dashscope_agenticx/agents/subagent.py
65 66 67 68 69 70 71 72 73 74 | |
register_subagent_tool
¶
register_subagent_tool() -> None
Wire subagent_invoke into the tool registry. Called from tools/platform.register_one_capability when local.subagent is enabled.
Source code in src/dashscope_agenticx/agents/subagent.py
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 | |
bind_delegate_context
¶
bind_delegate_context(agent, config)
Bind parent/config for one runtime context without global overwrite.
Source code in src/dashscope_agenticx/agents/delegate.py
62 63 64 65 66 67 68 69 70 71 | |