9 Commits

Author	SHA1	Message	Date
CoreRasurae	f9fea9e208	feat(skills): add skill package schema and agent-side skill loading support ... Extends the Package Registry Standard with a normative Skill package schema (§16) aligned with the open agentskills.io Agent Skills format, and adds an optional `skills` field to `type: llm` agent configs so an Actor can attach one or more resolved Skill packages to an agent. SkillLoader (new) resolves each `skills` reference through the existing cleveractors.registry client (registry:/ID:/local: schemes), mirroring the established template package-reference resolution pattern in cleveractors.templates.base._resolve_package_ref rather than introducing a parallel resolution path. SkillValidator (new) checks resolved content against the D-2 schema (name/description constraints lifted from agentskills.io, resource path/encoding rules) and computes a content-addressed package_id via the existing Canonicalizer. Resolved skills are disclosed to the model in three stages, per D-4: discovery (name+description folded into system_prompt), activation (a synthesized `skill` tool call returns full instructions), and execution (a further call reads a bundled resource, reusing file_read's offset/max_chars pagination convention from ADR-2033). All registry awareness lives in SkillLoader at the factory layer; LLMAgent only gains a `_skills` value forwarded through its existing tool-call context, and ToolAgent gains one new built-in tool handler — neither imports anything from cleveractors.registry. The `skills` field itself is documented only in ADR-2034, not mirrored into docs/index.md, matching how ADR-2031/ADR-2032 handled their own new LLM agent config fields (graduation into the normative spec is deferred to a future ADR). The Skill package schema, which has no other home, is appended as a new §16 in docs/actor-registry-standard.md (after the original §1-15 body, with a version bump to 1.1.0) rather than spliced into the existing §3.2 package-type table. 68 Behave scenarios cover schema validation, all three reference schemes, loader orchestration, factory/agent integration, and the ToolAgent skill tool (activation, resource reads, pagination, error paths). A Robot Framework suite exercises the same flow against a real on-disk skill file and real LocalPackageStore/PackageContentResolver resolution end to end, mocking only the LLM API call. Coverage: 96.9% (threshold 96.5%); full nox suite green; ASV shows no significant performance change. ISSUES CLOSED: #88	2026-08-01 16:40:28 +01:00
CoreRasurae	4fe14c5b77	feat(agents): add offset-based pagination to file_read ... `file_read` always read from position 0; `max_chars` (ADR-2030 D-3) only bounded where the returned content stopped, so once a large file was truncated there was no way to retrieve the next chunk short of falling back to the `shell` tool (`tail -c +N`, `sed -n`, `dd skip=...`) — the same class of awkward, error-prone detour ADR-2030 D-4 already eliminated for file paths mistaken for shell commands. Adds an optional `offset` character-position argument (default 0, byte-for-byte identical output when omitted) to both the tool schema (`llm_tools._BUILTIN_TOOL_SCHEMAS["file_read"]`) and the implementation (`ToolAgent._file_read_tool`). Combined with `max_chars` it returns the window `[offset, offset + max_chars)`, and the `[FILE_READ_SUCCESS]` header now signals continuation: `MORE_CONTENT_AT_OFFSET: N` when more content remains (N is the exact next offset, so callers never compute `offset + max_chars` themselves), or `NO_MORE_CONTENT_AT_OFFSET: N` when the requested offset is at or beyond end-of-file — a success response with empty content, not an error, since that is the expected terminal state of a correctly-paginating caller. Negative or non-integer offsets raise `ExecutionError`, mirroring the existing `max_chars` validation pattern. See docs/adr/ADR-2033-file-read-offset-pagination.md for the full set of design decisions, including why directory-listing pagination and byte-level seeking are deferred to a future issue. ISSUES CLOSED: #83	2026-07-31 08:53:31 +00:00
CoreRasurae	55734cd512	feat(agents): add LLM agent retry mechanisms with exponential backoff ... - Documents the retry feature implementation (issue #69, ADR-2032) Introduce configurable retry mechanisms (ADR-2032) for all LLM agent communications (main agent and pruning agent) with exponential backoff. - New config fields: max_retries (default 7), max_retry_time (default 60s) -1 sentinel disables the corresponding guard (infinite retries/time) - Exponential backoff: initial 0.5s, doubled each retry - Termination: whichever comes first (max_retries or max_retry_time), with -1 disabling the respective check - Counter and accumulated wait time reset on success - Timeout ExecutionError includes URL, actor graph name, and retry stats - Uniform scope: applies to both main agent and pruning agent - Timeout raises ExecutionError(kind="timeout") with URL, actor graph name, retry count, and accumulated wait time in the message (D-7) - Same client/connection reused across retries, no re-establishment (D-6) - Uniform scope: applies to both main agent and pruning agent (D-5) - Graph name threaded through state metadata and ContextVar for error reporting - BDD tests (7 scenarios) for retry behaviour including -1 sentinel cases - Reject max_retries/max_retry_time values < -1 with ConfigurationError - Reset current_graph_name ContextVar after node execution - Wrap no-tools astream() with per-chunk granular retry via call_with_retry - Update ADR D-7 with symmetrical disabled-guard example - Update CHANGELOG to reflect full feature scope ISSUES CLOSED: #69	2026-07-03 16:00:11 +01:00
CoreRasurae	964e87cc0f	feat(tool-loop): add token-budget awareness and tool output pruning ... Implement token-budget awareness (§4.4.7) and tool output pruning (§4.4.8-9) for the multi-turn tool-call loop to prevent context-window exhaustion. Token budget: tracks estimated token count before each ainvoke(), emits warning at 75% budget, injects synthesis prompt at exhaustion with one final tool-call round. Estimation via chat_model.get_num_tokens() with len(content)//4 heuristic fallback. Config key: token_budget_percent. Tool output pruning: implicit LLM extraction pass scoped to file_read calls. Schema augmentation injects output_prune (bool) and output_prune_context (string) meta-arguments. Pruning model responds with [PRUNE_INFO_START/END] and [PRUNE_OUTPUT_START/END] markers. Config keys: allow_tool_output_pruning, pruning_model. - Capture output_prune value in budget synthesis flow with proper guard - Fix ADR D-4: synthesis prompt is HumanMessage not SystemMessage - Fix Robot tests: replace /dev/null with temp file path ADR-2031 documents all specification extensions. 21 new BDD scenarios, 5 Robot integration tests, 16 ASV benchmarks. ISSUES CLOSED: #61	2026-06-26 18:21:14 +01:00
CoreRasurae	227e2feece	feat(agents): implement multi-turn tool-call loop and sandbox improvements ... Implements the complete LLM agent tool-calling pipeline — the tool-calling path was broken in multiple ways: tools from agent config were not passed to the LLM, tool execution was single-pass (the model could not see tool results or make follow-up calls), tool errors were discarded, and shell/ python_exec tools were never registered. Key changes: - Multi-turn tool-call loop: passes tools to the LLM via ainvoke(tools=...) and re-invokes after each batch of ToolResults, with a configurable round limit (tool_max_rounds config / TOOL_MAX_ROUNDS env var, default 20). - Tool schema module (llm_tools.py): normalize_tool_entry() converts string tool names and config dicts to OpenAI function-calling format with full parameter schemas and LLM-facing guidance (max_chars for file_read, sandbox builtins for python_exec, etc.). - file_read enhancements: directory listing with file sizes and type indicators, max_chars truncation to prevent context overflow, shell command detection with redirect to shell tool, file-not-found recovery hints with parent directory listing. - python_exec sandbox: stdout capture so print() produces visible output, NameError guidance directing LLM to file_read/file_write instead of using open(). - shell/python_exec tool registration in builtin_tools when allow_shell / exec_python is enabled. - create_subprocess_shell for shell commands (was create_subprocess_exec, which blocks pipes/redirections/chains). - Tool error propagation: ExecutionError/ConfigurationError details included in ToolMessages for LLM self-correction. - Stuck-model recovery: injects synthesizing prompt when model exhausts tool rounds without producing content. - LLM provider error details preserved in ExecutionError messages instead of generic "LLM processing failed". - Empty message filtering in _prepare_conversation_history() prevents whitespace-only messages from polluting downstream conversation history in multi-agent pipelines. Closes #59	2026-06-23 12:39:20 +01:00
CoreRasurae	9dc3f7910b	docs(registry): add MkDocs API documentation and usage examples for Package Registry Client ... Created comprehensive MkDocs-formatted API documentation under docs/registry/ covering all public API surfaces from the registry subsystem with real-life constructive examples: - index.md: Architecture overview, module relationships, quickstart - types.md: PackageType, PackageId, PackageReference, PackageContent - client.md: RegistryClient with all 4 endpoints, auth modes, async patterns - canonical.md: Canonicalizer pipeline — NFC, RFC-8785, SHA-1, lifecycle stripping - resolver.md: ReferenceResolver — 3 reference schemes, version alias resolution - exceptions.md: RegistryError hierarchy — all 9 typed exceptions with HTTP mapping - cache.md: RegistryCache — LRU eviction, TTL, SHA-1 tamper detection, singleflight - integration.md: 4 end-to-end workflows (ordering pipeline, email categorization, CI/CD verification, multi-tenant provisioning) Updated mkdocs.yml nav tree with docs/registry/ entries. Refs: #51	2026-06-17 14:09:28 +00:00
CoreRasurae	e8bd348c77	feat(registry): implement RegistryError hierarchy with typed exceptions ... Add RegistryError base with message, details, and original_reference fields. Implement all 9 typed exception types per Package Registry Standard §13.2: PackageNotFoundError, InvalidPackageIdError, InvalidPackageReferenceError, VersionNotFoundError, ValidationError, AuthenticationRequiredError, AccessDeniedError, ConflictError, and RegistryNetworkError. RegistryNetworkError carries status_code and url for transport failures. __str__ includes original_reference when available. exception_for_status() maps HTTP codes to typed exceptions. _ERROR_TYPE_MAP enables error-type parsing from JSON error bodies. 23 Behave BDD scenarios in features/registry_exceptions.feature. 12 Robot Framework integration tests in robot/exceptions.robot. Existing registry_http_client tests updated for InternalServerError removal. ISSUES CLOSED: #29	2026-06-11 20:44:54 +01:00
CoreRasurae	f787b52c7e	docs: Setup project documentation	2026-05-26 22:13:33 +01:00
CoreRasurae	55ce2acfdf	chore: Base repo structure commit	2026-05-26 21:45:54 +01:00