Documentation
¶
Overview ¶
Package tools implements application-owned coding tools for one workspace.
Index ¶
- Constants
- Variables
- func NewCatalog(tree *workspace.Tree, limits Limits, options ...CatalogOption) (*catalog.Catalog, error)
- func NewHistoryTool(bind func(context.Context) (*session.ArchiveReader, error)) agent.Tool
- func NewKillBackgroundTool(kill KillBackground, known KnownBackgroundIDs) agent.Tool
- func NewSchedulerCatalog(store SchedulerSurface) (*catalog.Catalog, error)
- func NewSchedulerCreateTool(store SchedulerSurface) agent.Tool
- func NewSchedulerDeleteTool(store SchedulerSurface) agent.Tool
- func NewSchedulerListTool(store SchedulerSurface) agent.Tool
- func NewTaskCatalog(plan func() tasklist.Snapshot) (*catalog.Catalog, error)
- func NewTaskOutputTool(read ReadBackgroundTasks, known KnownBackgroundIDs) agent.Tool
- func NewUpdateGoalCatalog(update UpdateGoal) (*catalog.Catalog, error)
- func NewUpdateGoalTool(update UpdateGoal) agent.Tool
- func NewUseToolTool(dispatch catalog.UseToolDispatch) agent.Tool
- func NewWaitTasksTool(read ReadBackgroundTasks, known KnownBackgroundIDs) agent.Tool
- type CatalogOption
- func WithControlledMonitor(tool agent.Tool) CatalogOption
- func WithControlledShell(tool agent.Tool) CatalogOption
- func WithKillBackground(kill KillBackground) CatalogOption
- func WithKnownBackgroundIDs(known KnownBackgroundIDs) CatalogOption
- func WithPlanFile(file PlanFile) CatalogOption
- func WithReadBackgroundTasks(read ReadBackgroundTasks) CatalogOption
- func WithSessionMediaRead(read SessionMediaRead) CatalogOption
- func WithTaskLogRead(read TaskLogRead) CatalogOption
- type GoalDeclaration
- type GoalError
- type KillBackground
- type KnownBackgroundIDs
- type Limits
- type MonitorHandler
- func NewMonitorHandler(registry *background.Registry) *MonitorHandler
- func NewMonitorHandlerForSandbox(registry *background.Registry, sandbox config.SandboxMode, ...) *MonitorHandler
- func NewMonitorHandlerForSandboxWithOwner(registry *background.Registry, sandbox config.SandboxMode, ...) *MonitorHandler
- func (h *MonitorHandler) Decl() ai.Tool
- func (h *MonitorHandler) Detach(ctx context.Context, call agent.ToolCall, prepared approval.PreparedExecution) ([]ai.Part, error)
- func (h *MonitorHandler) Operation(ctx context.Context, call agent.ToolCall) (execution.OperationSpec, error)
- func (h *MonitorHandler) Render(result execution.Result, runErr error) ([]ai.Part, error)
- type PlanFile
- type ReadBackgroundTasks
- type RecoveryError
- type ResultBackground
- type ResultCounts
- type ResultExecution
- type ResultExecutionStream
- type ResultHeader
- type ResultKill
- type ResultNext
- type ResultProblem
- type ResultTaskOutput
- type ResultTaskOutputs
- type SchedulerSurface
- type SessionMediaRead
- type ShellHandler
- func NewShellHandler() *ShellHandler
- func NewShellHandlerForNetwork(mode config.SandboxNetworkMode) *ShellHandler
- func NewShellHandlerForSandbox(sandbox config.SandboxMode, networkMode config.SandboxNetworkMode) *ShellHandler
- func NewShellHandlerForSandboxWithOwner(registry *background.Registry, sandbox config.SandboxMode, ...) *ShellHandler
- func (h *ShellHandler) Decl() ai.Tool
- func (h *ShellHandler) Detach(ctx context.Context, call agent.ToolCall, prepared approval.PreparedExecution) ([]ai.Part, error)
- func (h *ShellHandler) Detaches(call agent.ToolCall) bool
- func (h *ShellHandler) Operation(ctx context.Context, call agent.ToolCall) (execution.OperationSpec, error)
- func (h *ShellHandler) Render(result execution.Result, runErr error) ([]ai.Part, error)
- type TaskLogRead
- type UpdateGoal
Constants ¶
const ( // SchedulerCreateName schedules a prompt on an interval, or updates one in // place by task_id. SchedulerCreateName = "scheduler_create" // SchedulerDeleteName cancels a scheduled task by id. SchedulerDeleteName = "scheduler_delete" // SchedulerListName lists what is scheduled. SchedulerListName = "scheduler_list" )
The three model-facing scheduler Tool names.
const ( // TaskOutputName is the model-facing name of the Tool that reads one // background task's output by id. It is the name a completion's pointer // line promises. TaskOutputName = background.TaskOutputToolName // WaitTasksName is the model-facing name of the Tool that blocks until // background tasks complete. WaitTasksName = "wait_tasks" // TaskOutputModePoll is a non-blocking snapshot. TaskOutputModePoll = "poll" // TaskOutputModeWaitAll waits for every asked id. TaskOutputModeWaitAll = "wait_all" // TaskOutputModeWaitAny returns at the first completion. TaskOutputModeWaitAny = "wait_any" )
const ApplyPatchName = "apply_patch"
ApplyPatchName is the model-facing workspace edit tool.
const HistoryName = "session_history"
HistoryName is the session-bound read-only history retrieval tool.
const KillBackgroundName = background.KillTaskToolName
KillBackgroundName is the model-facing name of the Tool that stops one background task. It is the name the monitor Tool's own description and the catch-up notice already promise.
const (
// MonitorName is the model-facing name of the background monitor Tool.
MonitorName = monitorName
)
const PlanCatalogID = "coding.plan"
PlanCatalogID is the exact local provenance of the plan-mode tool pair.
const ( // ShellMaximumOutput is the shell operation's own output ceiling. A // backgrounded command's log keeps this bound, the same one the foreground // collector uses. ShellMaximumOutput = 16 << 20 )
const UpdateGoalName = "update_goal"
UpdateGoalName is the model-facing name of the Tool that declares progress, blockage, or completion for the running Goal.
const UseToolName = "use_tool"
UseToolName is the model-facing name of the Tool that calls a tool the current snapshot hides, by name.
Variables ¶
var ( // ErrGoalNotRunning refuses every declaration when no Goal run exists. The // Tool is offered outside a Goal run, so this is a sentence rather than an // unknown Tool. ErrGoalNotRunning = &GoalError{Code: "goal_not_running", Text: "no Goal run is in progress"} // ErrGoalNotActive refuses a completion or failure declaration against a // Goal that is paused or already finished. ErrGoalNotActive = &GoalError{Code: "goal_not_active", Text: "the Goal is not active"} )
Refusals the runtime answers a declaration with.
Functions ¶
func NewCatalog ¶
func NewCatalog( tree *workspace.Tree, limits Limits, options ...CatalogOption, ) (*catalog.Catalog, error)
NewCatalog returns the application-owned coding tool catalog.
func NewHistoryTool ¶ added in v0.1.5
NewHistoryTool retrieves only archives authorized by a fresh binding on every valid invocation. The application derives that binding from its current active checkpoint path. The callback must not grant permission based on tool arguments. No concurrency-safety promise is inferred for the application callback.
func NewKillBackgroundTool ¶ added in v0.1.9
func NewKillBackgroundTool(kill KillBackground, known KnownBackgroundIDs) agent.Tool
NewKillBackgroundTool builds the model-facing stop Tool. It addresses one background task or child id and reports the registry's own outcome vocabulary: killed, already_exited, or not_found. A not-found stop enumerates the ids the registry knows, so a model that lost an id can recover.
func NewSchedulerCatalog ¶ added in v0.1.9
func NewSchedulerCatalog(store SchedulerSurface) (*catalog.Catalog, error)
NewSchedulerCatalog returns the Agent-mode application catalog of scheduled task Tools. It is offered exactly where todo_write is offered, and a nil store offers none of them.
func NewSchedulerCreateTool ¶ added in v0.1.9
func NewSchedulerCreateTool(store SchedulerSurface) agent.Tool
NewSchedulerCreateTool builds the model-facing create Tool. It creates a recurring scheduled task or updates an existing one in place.
func NewSchedulerDeleteTool ¶ added in v0.1.9
func NewSchedulerDeleteTool(store SchedulerSurface) agent.Tool
NewSchedulerDeleteTool builds the model-facing cancel Tool. An id that does not exist reports success: false rather than failing the call.
func NewSchedulerListTool ¶ added in v0.1.9
func NewSchedulerListTool(store SchedulerSurface) agent.Tool
NewSchedulerListTool builds the model-facing list Tool.
func NewTaskCatalog ¶
NewTaskCatalog returns the Agent-mode application task progress tool. plan returns the current projected plan, which the fold needs so a merge reports the plan's real totals; a nil provider validates the call against the call alone, so the auto-upgrade net cannot fire and a replace is the only mode.
func NewTaskOutputTool ¶ added in v0.1.9
func NewTaskOutputTool(read ReadBackgroundTasks, known KnownBackgroundIDs) agent.Tool
NewTaskOutputTool builds the model-facing task-output Tool. It reads one or more background tasks or delegated subagents by id and reports each one's status, output, and exit code; a positive timeout_ms waits instead of taking a snapshot. A not-found id enumerates the task ids the registry knows, so a model that lost an id can recover it.
func NewUpdateGoalCatalog ¶ added in v0.1.9
func NewUpdateGoalCatalog(update UpdateGoal) (*catalog.Catalog, error)
NewUpdateGoalCatalog returns the model-facing Goal declaration Tool. It is offered wherever the Goal harness can run, and a nil channel offers none.
func NewUpdateGoalTool ¶ added in v0.1.9
func NewUpdateGoalTool(update UpdateGoal) agent.Tool
NewUpdateGoalTool builds the model-facing declaration Tool. It carries the one runtime channel that owns the Goal, so the declaration is answered against the run's own state.
func NewUseToolTool ¶ added in v0.1.9
func NewUseToolTool(dispatch catalog.UseToolDispatch) agent.Tool
NewUseToolTool builds the model-facing dispatch Tool. It carries the one dispatcher that owns the catalog and the policy, so a name it reaches is resolved exactly as a direct call would be resolved, and the target's own result is what the model receives. A Tool built without a dispatcher refuses every call, which is what a surface that cannot dispatch still wants.
func NewWaitTasksTool ¶ added in v0.1.9
func NewWaitTasksTool(read ReadBackgroundTasks, known KnownBackgroundIDs) agent.Tool
NewWaitTasksTool builds the model-facing blocking-wait Tool. It blocks until the listed background tasks or delegated subagents complete, or until the budget elapses, and reports the same record the task-output Tool does. It exists because its mode carries the one behaviour the task-output Tool has no place for: wait_any returns at the first completion.
Types ¶
type CatalogOption ¶
type CatalogOption func(*catalogConfig) error
CatalogOption adds an explicitly constructed coding tool.
func WithControlledMonitor ¶ added in v0.1.9
func WithControlledMonitor(tool agent.Tool) CatalogOption
WithControlledMonitor adds the monitor wrapper returned by approval.Controller. A monitor starts a process like shell does, so it is offered in exactly the modes that offer shell.
func WithControlledShell ¶
func WithControlledShell(tool agent.Tool) CatalogOption
WithControlledShell adds the shell wrapper returned by approval.Controller. Passing the raw ShellHandler is impossible because it does not implement agent.Tool.
func WithKillBackground ¶ added in v0.1.9
func WithKillBackground(kill KillBackground) CatalogOption
WithKillBackground adds the one control operation a background-task stop routes through. A catalog built without it offers no stop Tool, which is what a capability mode that keeps no monitor also keeps no stop for.
func WithKnownBackgroundIDs ¶ added in v0.1.9
func WithKnownBackgroundIDs(known KnownBackgroundIDs) CatalogOption
WithKnownBackgroundIDs adds the enumeration a not-found stop names, so the model can recover an id it lost. A catalog built without it reports a bare not-found sentence, which is what a caller that keeps no id list still wants.
func WithPlanFile ¶
func WithPlanFile(file PlanFile) CatalogOption
WithPlanFile admits the plan-mode file as an additional patch target while plan mode is active.
func WithReadBackgroundTasks ¶ added in v0.1.9
func WithReadBackgroundTasks(read ReadBackgroundTasks) CatalogOption
WithReadBackgroundTasks adds the one read operation the task-output and blocking-wait Tools route through. A catalog built without it offers neither Tool, which is what a capability mode that keeps no registry also keeps no read for.
func WithSessionMediaRead ¶ added in v0.1.9
func WithSessionMediaRead(read SessionMediaRead) CatalogOption
WithSessionMediaRead admits this session's media files to the read Tool. The boundary resolves one exact path; the Tool never learns the session directory, and a value it does not admit is refused as an outside-workspace path. The runtime owns which paths are admitted, so the boundary is the only extension point: a catalog built without it offers no session media read.
func WithTaskLogRead ¶ added in v0.1.9
func WithTaskLogRead(read TaskLogRead) CatalogOption
WithTaskLogRead admits this session's background task logs to the read Tool. The boundary resolves one exact path; the Tool never learns the session directory, and a value it does not admit is refused as an outside-workspace path.
type GoalDeclaration ¶ added in v0.1.9
type GoalDeclaration struct {
// Completed reports that the Goal is fully achieved. It moves when the
// completion question is asked, never who answers it.
Completed bool
// Message is a short progress note, recorded and echoed without changing the
// run.
Message string
// BlockedReason is a failure signal: the same problem has defeated three or
// more attempts. It pauses the Goal for a user decision.
BlockedReason string
}
GoalDeclaration is one model declaration about the running Goal: a progress note, a failure signal, or a claim of completion. The three channels are the reference's own, and a declaration is never evidence — the auditor reads the workspace and the recorded tool results, not the worker's confidence.
func (GoalDeclaration) Validate ¶ added in v0.1.9
func (d GoalDeclaration) Validate() error
Validate bounds the two text channels.
type GoalError ¶ added in v0.1.9
GoalError names why a declaration was refused. The code is the stable reason; the text is the sentence the model reads.
func (*GoalError) ToolErrorCode ¶ added in v0.1.9
ToolErrorCode implements the coded tool failure the result envelope renders.
type KillBackground ¶ added in v0.1.9
type KillBackground func(context.Context, string) (background.Outcome, background.Subject, error)
KillBackground is the one operation a stop routes through. The model Tool, the tasks-pane control, and the runtime control plane all call the same method, so there is never a second control path to keep in step. The subject comes back beside the outcome because the two producers are worded differently: a background task is stopped outright, while a child's cancellation is only initiated and the child winds down afterwards.
type KnownBackgroundIDs ¶ added in v0.1.9
KnownBackgroundIDs lists the ids the control surface still knows, so a not-found stop can name them instead of leaving the model with no way to recover a lost id. It is optional; a nil value omits the enumeration.
type Limits ¶
type Limits struct {
OutputBytes int
FileBytes int64
ReadLines int
ListEntries int
GlobEntries int
GrepMatches int
GrepLineBytes int
ScanEntries int
GrepFiles int
GlobTimeout time.Duration
GrepTimeout time.Duration
PatchBytes int
PatchFiles int
PatchTotalBytes int64
PatchTimeout time.Duration
}
Limits bounds filesystem work and model-visible output for coding tools.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits returns production coding-tool budgets.
type MonitorHandler ¶ added in v0.1.9
type MonitorHandler struct {
// contains filtered or unexported fields
}
MonitorHandler prepares and renders background watches. Like the shell handler it deliberately does not implement agent.Tool: only an approval Controller may create the registerable wrapper, so a monitor is authorized through the same permit, journal, policy, sandbox, and executor path as any other controlled operation. The only difference is that its run is detached from the Tool call that started it.
func NewMonitorHandler ¶ added in v0.1.9
func NewMonitorHandler(registry *background.Registry) *MonitorHandler
NewMonitorHandler constructs the non-registerable monitor operation handler.
func NewMonitorHandlerForSandbox ¶ added in v0.1.9
func NewMonitorHandlerForSandbox( registry *background.Registry, sandbox config.SandboxMode, networkMode config.SandboxNetworkMode, ) *MonitorHandler
NewMonitorHandlerForSandbox constructs a monitor handler for one effective filesystem profile and Network policy, matching the shell handler's boundary.
func NewMonitorHandlerForSandboxWithOwner ¶ added in v0.1.9
func NewMonitorHandlerForSandboxWithOwner( registry *background.Registry, sandbox config.SandboxMode, networkMode config.SandboxNetworkMode, owner func() string, ) *MonitorHandler
NewMonitorHandlerForSandboxWithOwner constructs a monitor handler that stamps each task it starts with the spawning interaction's id. The owner provider is read at detach time, so it reports the interaction that is running when the task starts rather than the one that built the handler.
func (*MonitorHandler) Decl ¶ added in v0.1.9
func (h *MonitorHandler) Decl() ai.Tool
Decl returns the monitor declaration consumed by the approval Controller.
func (*MonitorHandler) Detach ¶ added in v0.1.9
func (h *MonitorHandler) Detach( ctx context.Context, call agent.ToolCall, prepared approval.PreparedExecution, ) ([]ai.Part, error)
Detach starts the run on the background registry and returns the model-facing receipt. The run outlives this call: it keeps the Tool call's ambient values through context.WithoutCancel but not its cancellation, and the registry ends it on a kill, its deadline, or Runtime teardown.
func (*MonitorHandler) Operation ¶ added in v0.1.9
func (h *MonitorHandler) Operation( ctx context.Context, call agent.ToolCall, ) (execution.OperationSpec, error)
Operation strictly decodes one call into the monitor's execution contract.
func (*MonitorHandler) Render ¶ added in v0.1.9
Render projects a terminal monitor result into the coding tool envelope. It is reached only when a monitor never detached: an authorization failure, a decode failure, or a run that could not be handed off. A monitor's own output is delivered as events, not as this result.
type PlanFile ¶
type PlanFile struct {
Path func() string
Admitted func() bool
Read func(context.Context) (string, error)
Write func(context.Context, string) error
}
PlanFile is the injected plan-mode file boundary. The patch tool applies changes to this exact file when plan mode admits it.
type ReadBackgroundTasks ¶ added in v0.1.9
type ReadBackgroundTasks func( ctx context.Context, ids []string, mode string, budget time.Duration, ) ([]background.TaskOutput, background.WaitOutcome)
ReadBackgroundTasks resolves a background task or a delegated child by id. mode is one of the TaskOutputMode constants; budget is the effective wait budget, zero for a poll. Records come back ordered as the ids were asked, with an unknown id reported as an unfound record.
type RecoveryError ¶
type RecoveryError struct {
Applied bool
RecoveryPaths []string
// contains filtered or unexported fields
}
RecoveryError means the patch could not finish or cleanly restore every path. RecoveryPaths are workspace-relative materials retained for recovery.
func (*RecoveryError) Unwrap ¶
func (e *RecoveryError) Unwrap() error
Unwrap returns the transaction or cleanup failure.
type ResultBackground ¶ added in v0.1.9
type ResultBackground struct {
TaskID string `json:"task_id"`
Kind string `json:"kind"`
TimeoutMS int64 `json:"timeout_ms"`
Persistent bool `json:"persistent"`
}
ResultBackground is the structured output of one Tool call that started a background task: the task id the model addresses, the kind it registered under, the resolved deadline, and whether it is persistent. A persistent monitor resolves its deadline to zero.
type ResultCounts ¶
type ResultCounts struct {
Lines int `json:"lines,omitempty"`
Bytes int `json:"bytes,omitempty"`
Entries int `json:"entries,omitempty"`
Files int `json:"files,omitempty"`
Matches int `json:"matches,omitempty"`
Scanned int `json:"scanned,omitempty"`
Skipped int `json:"skipped,omitempty"`
TruncatedLines int `json:"truncated_lines,omitempty"`
}
ResultCounts summarizes bounded work performed by a coding tool.
type ResultExecution ¶
type ResultExecution struct {
Status string `json:"status"`
ExitCode *int `json:"exit_code,omitempty"`
Signal string `json:"signal,omitempty"`
DurationMS int64 `json:"duration_ms"`
Stdout ResultExecutionStream `json:"stdout"`
Stderr ResultExecutionStream `json:"stderr"`
}
ResultExecution summarizes one bounded local process outcome.
type ResultExecutionStream ¶
type ResultExecutionStream struct {
Bytes int64 `json:"bytes"`
Truncated bool `json:"truncated,omitempty"`
Sanitized bool `json:"sanitized,omitempty"`
}
ResultExecutionStream summarizes observed output without embedding content.
type ResultHeader ¶
type ResultHeader struct {
Schema string `json:"schema"`
OK bool `json:"ok"`
Tool string `json:"tool"`
Code string `json:"code,omitempty"`
Truncated bool `json:"truncated,omitempty"`
Reason string `json:"reason,omitempty"`
Problem *ResultProblem `json:"problem,omitempty"`
Counts ResultCounts `json:"counts,omitzero"`
Next ResultNext `json:"next,omitzero"`
Execution *ResultExecution `json:"execution,omitempty"`
Background *ResultBackground `json:"background,omitempty"`
Kill *ResultKill `json:"kill,omitempty"`
TaskOutput *ResultTaskOutput `json:"task_output,omitempty"`
TaskOutputs *ResultTaskOutputs `json:"task_outputs,omitempty"`
Diagnostic *execution.SandboxDiagnostic `json:"diagnostic,omitempty"`
}
ResultHeader is the machine-readable first line of every coding-tool result.
func ParseResult ¶
func ParseResult(value string) (ResultHeader, string, error)
ParseResult decodes a coding-tool result without making consumers redefine the versioned envelope contract. Body is returned without transformation.
type ResultKill ¶ added in v0.1.9
ResultKill is the structured output of one background-task stop: the id the model addressed and the registry's own outcome.
type ResultNext ¶
type ResultNext struct {
Offset *int `json:"offset,omitempty"`
}
ResultNext identifies a continuation point for a truncated result.
type ResultProblem ¶
type ResultProblem struct {
Field string `json:"field,omitempty"`
Retryable bool `json:"retryable"`
Hint string `json:"hint,omitempty"`
}
ResultProblem describes a safe correction for a failed tool call.
type ResultTaskOutput ¶ added in v0.1.9
type ResultTaskOutput struct {
TaskID string `json:"task_id"`
Command string `json:"command,omitempty"`
Status string `json:"status"`
ExitCode *int `json:"exit_code,omitempty"`
Started string `json:"started,omitempty"`
Ended string `json:"ended,omitempty"`
DurationSecs float64 `json:"duration_secs"`
Output string `json:"output,omitempty"`
OutputFile string `json:"output_file,omitempty"`
Truncated bool `json:"truncated,omitempty"`
TruncationHint string `json:"truncation_hint,omitempty"`
RawOutputBytes int64 `json:"raw_output_bytes"`
}
ResultTaskOutput is one background task's structured output record. Its fields are the reference's, so a reader that knows that shape reads this one.
type ResultTaskOutputs ¶ added in v0.1.9
type ResultTaskOutputs struct {
Mode string `json:"mode"`
Results []ResultTaskOutput `json:"results"`
Summary string `json:"summary"`
}
ResultTaskOutputs is the structured payload of a multi-id read: the mode the read ran under, one record per asked id in order, and the completed-count summary the body ends with.
type SchedulerSurface ¶ added in v0.1.9
type SchedulerSurface interface {
Create(context.Context, scheduler.CreateRequest) (scheduler.Task, error)
Update(context.Context, string, scheduler.UpdateRequest) (scheduler.Task, error)
Delete(context.Context, string) (bool, error)
List(context.Context) ([]scheduler.Task, error)
}
SchedulerSurface is the injected store boundary the scheduler Tools read and write through. A catalog built without one offers no scheduler Tool.
type SessionMediaRead ¶ added in v0.1.9
type SessionMediaRead struct {
// Admit reports the admitted path for one requested value, or false when the
// value names no media file this session owns.
Admit func(string) (string, bool)
// Bytes bounds an admitted media file's size.
Bytes int64
}
SessionMediaRead is the injected exact-path read boundary for the current session's media files. A session media file lives in the session directory, outside the workspace tree, so the read Tool admits it by exact path and reads it under this boundary's own byte bound. The Tool learns nothing about directories: it asks this boundary whether one requested value is an admitted media file. The runtime owns which paths are admitted.
type ShellHandler ¶
type ShellHandler struct {
// contains filtered or unexported fields
}
ShellHandler prepares and renders shell operations. It deliberately does not implement agent.Tool; only an approval Controller may create the registerable wrapper.
func NewShellHandler ¶
func NewShellHandler() *ShellHandler
NewShellHandler constructs the non-registerable shell operation handler.
func NewShellHandlerForNetwork ¶
func NewShellHandlerForNetwork(mode config.SandboxNetworkMode) *ShellHandler
NewShellHandlerForNetwork constructs a Shell handler with the user-owned workspace-write network policy. The Config boundary validates mode.
func NewShellHandlerForSandbox ¶
func NewShellHandlerForSandbox( sandbox config.SandboxMode, networkMode config.SandboxNetworkMode, ) *ShellHandler
NewShellHandlerForSandbox constructs a Shell handler for one effective filesystem profile and Network policy. Read-only profiles request the read-only operation boundary so safe shell reads remain available while Policy rejects workspace and external writes before approval.
func NewShellHandlerForSandboxWithOwner ¶ added in v0.1.9
func NewShellHandlerForSandboxWithOwner( registry *background.Registry, sandbox config.SandboxMode, networkMode config.SandboxNetworkMode, owner func() string, ) *ShellHandler
NewShellHandlerForSandboxWithOwner constructs a Shell handler that can start a command in the background and stamp it with the spawning interaction's id. The owner provider is read at detach time, so it reports the interaction that is running when the command starts rather than the one that built the handler.
func (*ShellHandler) Decl ¶
func (h *ShellHandler) Decl() ai.Tool
Decl returns the shell declaration consumed by the approval Controller.
func (*ShellHandler) Detach ¶ added in v0.1.9
func (h *ShellHandler) Detach( ctx context.Context, call agent.ToolCall, prepared approval.PreparedExecution, ) ([]ai.Part, error)
Detach starts the command on the background registry and returns either the model-facing receipt or, when a positive block's wait caught the command's end, the ordinary shell result rendered from the task's own executor result. The run outlives this call: it keeps the Tool call's ambient values through context.WithoutCancel but not its cancellation, and the registry ends it on a kill, its deadline, or Runtime teardown.
func (*ShellHandler) Detaches ¶ added in v0.1.9
func (h *ShellHandler) Detaches(call agent.ToolCall) bool
Detaches reports whether this call takes the detached path. It decodes the arguments again — the controller decodes them when it builds the operation — because the arguments are bounded at 64 KiB and the decode is pure. A malformed call answers false, so it reaches the same decode error the synchronous path reports.
func (*ShellHandler) Operation ¶
func (h *ShellHandler) Operation( ctx context.Context, call agent.ToolCall, ) (execution.OperationSpec, error)
Operation strictly decodes one call into the fixed /bin/sh contract.
type TaskLogRead ¶ added in v0.1.9
type TaskLogRead struct {
// Admit reports the admitted path for one requested value, or false when the
// value names no log this session still owns.
Admit func(string) (string, bool)
// Bytes bounds an admitted log's size.
Bytes int64
}
TaskLogRead is the injected exact-path read boundary for a background task's own log. A log lives in the session directory, outside the workspace tree, so the read Tool admits it by exact path and reads it under this boundary's own byte bound rather than the workspace file bound. The Tool learns nothing about directories or task ids: it asks this boundary whether one requested value is an admitted log.
type UpdateGoal ¶ added in v0.1.9
type UpdateGoal func(context.Context, GoalDeclaration) (string, error)
UpdateGoal is the one runtime channel a declaration routes through. It answers with the sentence the model reads, or refuses with a named reason. A Tool built without one refuses every call, which is what a surface that owns no Goal harness still wants.