Tools, results and artifacts

Legacy host Read uses a zero-based offset and a positive line limit: offset 2, limit 2 selects only lines 3/4. Empty files and EOF return empty output; negative or non-integer windows fail. Selection metadata reports truncation and more lines. Edit requires a unique match unless replace_all=True; no match, ambiguous match, permission denial and explicit expected_sha256 conflicts leave the file unchanged. These two aliases now return canonical ToolResult (read numbered text in .output, status/error in their named fields), rather than successful strings containing errors. Direct callers expecting strings should use .output after checking .status. The existing validation/permission pipeline remains authoritative. Host compatibility remains host execution; Env read_file/edit_file keep their Env-only operations and one-based line_offset interface. No fallback to host or new isolation guarantee is implied. Register tools before running. execute(args, runtime_context) is the class-tool contract; run is compatibility only. Inspect ToolResult status, error_code, output, artifact_refs, outcome_unknown and worker_still_running. Successful text alone is insufficient. Parallel execution requires truthful concurrency declarations. Completion and declaration order differ. Publication is opt-in and platform/file-shape limited; cleanup never publishes. SandboxPublicationTool is an advanced, explicitly registered adapter despite its internal module name, not a default tool. 完整可运行教程 / Complete tutorial · API index Signatures and fields below are extracted from the pinned source. Signatures are reference material, not standalone programs. Source links bind the same runtime baseline. Any does not imply arbitrary objects are supported; use the behavioral contract above and the linked tutorial.

ToolRegistry

from qitos import ToolRegistry

Source @ 19f6258 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

registry = ToolRegistry()
registry.register(summarize_note)

Registry for function tools, bound methods, tool objects, and ToolSets.

ToolRegistry(*, auto_short_aliases: bool=True) -> Any (see behavior contract)

Parameter	Type	Default
`auto_short_aliases`	`bool`	`True`

ToolRegistry.register

register(item: Any, name: Optional[str]=None, meta: Optional[ToolMeta]=None) -> 'ToolRegistry'

Parameter	Type	Default
`item`	`Any`	`required`
`name`	`Optional[str]`	`None`
`meta`	`Optional[ToolMeta]`	`None`

Source

function_tool

from qitos.core.function_tool_decorator import function_tool

Source @ 19f6258 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

@function_tool(read_only=True, concurrency_safe=True)
def title(text: str) -> str:
    return text.split(":", 1)[0]

Decorator that creates a :class:`FunctionTool` from a plain function.

Can be used with or without parentheses::

    @function_tool
    def greet(name: str) -> str: ...

    @function_tool(name="custom", needs_approval=True)
    def greet(name: str) -> str: ...

Returns a :class:`FunctionTool` instance.

function_tool(func: Optional[Callable[..., Any]]=None, *, name: Optional[str]=None, description: Optional[str]=None, timeout_s: Optional[float]=None, max_retries: int=0, retry_policy: Optional[RetryPolicy]=None, on_failure: Optional[Callable]=None, read_only: bool=False, concurrency_safe: Optional[bool]=None, needs_approval: bool=False, **extra_meta: Any) -> Any

Parameter	Type	Default
`func`	`Optional[Callable[..., Any]]`	`None`
`name`	`Optional[str]`	`None`
`description`	`Optional[str]`	`None`
`timeout_s`	`Optional[float]`	`None`
`max_retries`	`int`	`0`
`retry_policy`	`Optional[RetryPolicy]`	`None`
`on_failure`	`Optional[Callable]`	`None`
`read_only`	`bool`	`False`
`concurrency_safe`	`Optional[bool]`	`None`
`needs_approval`	`bool`	`False`

BaseTool

from qitos.core.tool import BaseTool

Source @ 19f6258 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

# Class tools implement execute, not the compatibility run method.
class EchoTool(BaseTool):
    name = "echo"
    description = "Return a trusted input"
    def execute(self, args, runtime_context=None):
        return ToolResult(output=args)

Base abstraction for callable tools.

BaseTool(spec: ToolSpec) -> Any (see behavior contract)

Parameter	Type	Default
`spec`	`ToolSpec`	`required`

BaseTool.execute

execute(args: Dict[str, Any], runtime_context: Optional[Dict[str, Any]]=None) -> Any

Parameter	Type	Default
`args`	`Dict[str, Any]`	`required`
`runtime_context`	`Optional[Dict[str, Any]]`	`None`

Execute tool with optional runtime context.

Source

ToolResult

from qitos.core.tool_result import ToolResult

Source @ 19f6258 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

result = ToolResult(output={"title": "Session"})
print(result.status, result.output, result.outcome_unknown)

Lossless terminal outcome for one declared action/tool slot.

Field	Type	Default
`status`	`ToolResultStatus`	`'success'`
`output`	`Any`	`None`
`error`	`str \| None`	`None`
`metadata`	`Dict[str, Any]`	`field(default_factory=dict)`
`tool_name`	`str \| None`	`None`
`action_id`	`str \| None`	`None`
`model_output`	`Any`	`None`
`error_kind`	`ToolErrorKind \| None`	`None`
`error_code`	`str \| None`	`None`
`recoverable`	`bool`	`False`
`recovery_hint`	`str \| None`	`None`
`next_action`	`Dict[str, Any] \| None`	`None`
`complete`	`bool`	`True`
`truncated`	`bool`	`False`
`omitted`	`Dict[str, int]`	`field(default_factory=dict)`
`attempts`	`int`	`1`
`latency_ms`	`float`	`0.0`
`declared_effects`	`list[Dict[str, Any]]`	`field(default_factory=list)`
`filesystem_changes`	`list[Dict[str, Any]]`	`field(default_factory=list)`
`artifact_refs`	`tuple[ArtifactRef, ...]`	`()`
`normalized_request`	`Dict[str, Any]`	`field(default_factory=dict)`
`provenance`	`Dict[str, Any]`	`field(default_factory=dict)`
`worker_still_running`	`bool`	`False`
`attempt_id`	`AttemptIdentity \| None`	`None`
`effect_ref`	`str \| None`	`None`
`effect_state`	`EffectState`	`'no_effect_declared'`
`idempotency_ref`	`str \| None`	`None`
`retry_disposition`	`RetryDisposition`	`'not_evaluated'`
`reconciliation_required`	`bool`	`False`
`outcome_unknown`	`bool`	`False`
`late_result`	`bool`	`False`
`owner_generation`	`int \| None`	`None`
`stale_owner`	`bool`	`False`
`batch_closure`	`Dict[str, Any]`	`field(default_factory=dict)`
`schema_version`	`str`	`TOOL_RESULT_SCHEMA_VERSION`

ArtifactRef

from qitos.core.artifact import ArtifactRef

Source @ 19f6258 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

# ref is an ArtifactRef obtained from a tool result.
print(ref.sha256)
body = composition.agent.config["artifact_resolver"].resolve(ref).body

Portable content-addressed pointer; never an artifact body or host path.

Field	Type	Default
`artifact_id`	`str`	`required`
`resolver_key`	`str`	`required`
`sha256`	`str`	`required`
`media_type`	`str`	`required`
`byte_length`	`int`	`required`
`encoding`	`str`	`'binary'`
`sensitivity`	`str`	`'internal'`
`provenance_digest`	`Optional[str]`	`None`
`model_summary`	`Optional[str]`	`None`
`required`	`bool`	`True`
`schema_version`	`str`	`ARTIFACT_REF_SCHEMA_VERSION`

ArtifactRef.from_dict

from_dict(value: Any) -> 'ArtifactRef'

Parameter	Type	Default
`value`	`Any`	`required`

Source

ActionExecutionPolicy

from qitos.engine.action_executor import ActionExecutionPolicy

Source @ 19f6258 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

policy = ActionExecutionPolicy(mode="parallel", max_concurrency=2)
engine = Engine(NotesAgent(), runtime=RuntimeComposition(), action_execution_policy=policy)

Executor policy for action batches.

Field	Type	Default
`mode`	`str`	`'serial'`
`fail_fast`	`bool`	`False`
`max_concurrency`	`int`	`4`
`parallel_tool_names`	`FrozenSet[str] \| None`	`None`

SandboxPublicationTool

from qitos.kit.tool.internal.publication import SandboxPublicationTool

Source @ 19f6258 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

# Only after sandbox execution, with explicit publication authority:
publication = SandboxPublicationTool(
    composition.env, paths=["report.txt"],
    expected_input_digest=composition.env.input_digest,
)
composition.tool_registry.register(publication)

Opt-in tool restricted to paths and input digest approved by its caller.

SandboxPublicationTool(env: Any, *, paths: Iterable[str], expected_input_digest: str) -> Any (see behavior contract)

Parameter	Type	Default
`env`	`Any`	`required`
`paths`	`Iterable[str]`	`required`
`expected_input_digest`	`str`	`required`

SandboxPublicationTool.execute

execute(args: Any, runtime_context: Any=None) -> ToolResult

Parameter	Type	Default
`args`	`Any`	`required`
`runtime_context`	`Any`	`None`

Source

​ToolRegistry

​ToolRegistry.register

​function_tool

​BaseTool

​BaseTool.execute

​ToolResult

​ArtifactRef

​ArtifactRef.from_dict

​ActionExecutionPolicy

​SandboxPublicationTool

​SandboxPublicationTool.execute

ToolRegistry

ToolRegistry.register

function_tool

BaseTool

BaseTool.execute

ToolResult

ArtifactRef

ArtifactRef.from_dict

ActionExecutionPolicy

SandboxPublicationTool

SandboxPublicationTool.execute