toolshared

type AsyncCallback func(ctx context.Context, result *ToolResult)

type AsyncDeliveryMode string

type AsyncExecutor interface {
	Tool
	// ExecuteAsync runs the tool asynchronously. The callback cb will be
	// invoked (possibly from another goroutine) when the async operation
	// completes. cb is guaranteed to be non-nil by the caller (registry).
	ExecuteAsync(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult
}

type CompletionMedia struct {
	Ref         string `json:"ref"`
	Type        string `json:"type,omitempty"`
	Filename    string `json:"filename,omitempty"`
	ContentType string `json:"content_type,omitempty"`
}

type CompletionResult struct {
	Text  string            `json:"text,omitempty"`
	Media []CompletionMedia `json:"media,omitempty"`
}

type DeliverableItem struct {
	Ref         string `json:"ref"`
	Kind        string `json:"kind,omitempty"`
	Filename    string `json:"filename,omitempty"`
	ContentType string `json:"content_type,omitempty"`
	Delivered   bool   `json:"delivered,omitempty"`
}

type DeliverableReport struct {
	SchemaVersion string             `json:"schema_version,omitempty"`
	ReportID      string             `json:"report_id,omitempty"`
	ContentHash   string             `json:"content_hash,omitempty"`
	GeneratedAt   int64              `json:"generated_at,omitempty"`
	Summary       string             `json:"summary,omitempty"`
	Claims        []ReportClaim      `json:"claims,omitempty"`
	FieldDeltas   []ReportFieldDelta `json:"field_deltas,omitempty"`
	Provenance    map[string]string  `json:"provenance,omitempty"`
	Metadata      map[string]string  `json:"metadata,omitempty"`
	Extra         map[string]any     `json:"extra,omitempty"`
}

type DeliverableResult struct {
	Text      string             `json:"text,omitempty"`
	Artifacts []DeliverableItem  `json:"artifacts,omitempty"`
	Metadata  map[string]string  `json:"metadata,omitempty"`
	Report    *DeliverableReport `json:"report,omitempty"`
}

type DeliveryIntent string

type ExecRequest struct {
	Action     string            `json:"action"`
	Command    string            `json:"command,omitempty"`
	PTY        bool              `json:"pty,omitempty"`
	Background bool              `json:"background,omitempty"`
	Timeout    int               `json:"timeout,omitempty"`
	Env        map[string]string `json:"env,omitempty"`
	Cwd        string            `json:"cwd,omitempty"`
	SessionID  string            `json:"sessionId,omitempty"`
	Data       string            `json:"data,omitempty"`
}

type ExecResponse struct {
	SessionID    string        `json:"sessionId,omitempty"`
	SessionScope string        `json:"sessionScope,omitempty"`
	RestartSafe  *bool         `json:"restartSafe,omitempty"`
	Status       string        `json:"status,omitempty"`
	ExitCode     int           `json:"exitCode,omitempty"`
	Output       string        `json:"output,omitempty"`
	Error        string        `json:"error,omitempty"`
	Sessions     []SessionInfo `json:"sessions,omitempty"`
}

type FunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type LLMProvider interface {
	Chat(
		ctx context.Context,
		messages []Message,
		tools []ToolDefinition,
		model string,
		options map[string]any,
	) (*LLMResponse, error)
	GetDefaultModel() string
}

type LLMResponse struct {
	Content      string     `json:"content"`
	ToolCalls    []ToolCall `json:"tool_calls,omitempty"`
	FinishReason string     `json:"finish_reason"`
	Usage        *UsageInfo `json:"usage,omitempty"`
}

type LoopSemanticsProvider interface {
	ToolLoopSemantics() loopguard.Semantics
}

type Message struct {
	Role       string     `json:"role"`
	Content    string     `json:"content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

type OutboundDelivery struct {
	Channel          string                `json:"channel,omitempty"`
	ChatID           string                `json:"chat_id,omitempty"`
	ReplyToMessageID string                `json:"reply_to_message_id,omitempty"`
	Text             string                `json:"text,omitempty"`
	Media            []bus.MediaPart       `json:"media,omitempty"`
	Recovery         *bus.OutboundRecovery `json:"recovery,omitempty"`
}

type PromptMetadata struct {
	Layer  string
	Slot   string
	Source string
}

type PromptMetadataProvider interface {
	PromptMetadata() PromptMetadata
}

type ReportClaim struct {
	Kind       string            `json:"kind"`
	Text       string            `json:"text"`
	Confidence string            `json:"confidence,omitempty"`
	SourceRefs []string          `json:"source_refs,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

type ReportFieldDelta struct {
	Field string `json:"field"`
	From  string `json:"from,omitempty"`
	To    string `json:"to,omitempty"`
}

type SessionInfo struct {
	ID        string `json:"id"`
	Command   string `json:"command"`
	Status    string `json:"status"`
	PID       int    `json:"pid"`
	StartedAt int64  `json:"startedAt"`
}

type Tool interface {
	Name() string
	Description() string
	Parameters() map[string]any
	Execute(ctx context.Context, args map[string]any) *ToolResult
}

type ToolCall struct {
	ID        string         `json:"id"`
	Type      string         `json:"type"`
	Function  *FunctionCall  `json:"function,omitempty"`
	Name      string         `json:"name,omitempty"`
	Arguments map[string]any `json:"arguments,omitempty"`
}

type ToolDefinition struct {
	Type     string                 `json:"type"`
	Function ToolFunctionDefinition `json:"function"`
}

type ToolFunctionDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters"`
}

type ToolResult struct {
	// ForLLM is the content sent to the LLM for context.
	// Required for all results.
	ForLLM string `json:"for_llm"`

	// ForUser is the content sent directly to the user.
	// If empty, no user message is sent.
	// Silent=true overrides this field.
	ForUser string `json:"for_user,omitempty"`

	// Silent suppresses sending any message to the user.
	// When true, ForUser is ignored even if set.
	Silent bool `json:"silent"`

	// IsError indicates whether the tool execution failed.
	// When true, the result should be treated as an error.
	IsError bool `json:"is_error"`

	// Async indicates whether the tool is running asynchronously.
	// When true, the tool will complete later and notify via callback.
	Async bool `json:"async"`

	// AsyncDelivery controls how the final async result should be routed when
	// the background work completes.
	//
	// Empty means "use runtime default behavior".
	// Supported values:
	//   - user_only
	//   - parent_only
	//   - user_and_parent
	AsyncDelivery AsyncDeliveryMode `json:"async_delivery,omitempty"`

	// AsyncTaskID links an async result back to a durable task registry record
	// when the tool runtime has one, for example "subagent-42".
	AsyncTaskID string `json:"async_task_id,omitempty"`

	// TaskSuspended tells a durable task owner not to publish completion while
	// the child turn is owned by a pending human interaction.
	TaskSuspended bool `json:"-"`

	// Err is the underlying error (not JSON serialized).
	// Used for internal error handling and logging.
	Err error `json:"-"`

	// Media contains media store refs produced by this tool.
	// When non-empty, the agent will publish these as OutboundMediaMessage.
	Media []string `json:"media,omitempty"`

	// Completion carries a structured child-run result for parent agents.
	// It is populated by sub-turns/delegation/spawn handoffs so the parent can
	// see both text and media refs without scraping prose.
	// Deprecated for new consumers: use Deliverable for produced outputs and
	// keep Completion only as a legacy child-run handoff adapter.
	Completion *CompletionResult `json:"completion,omitempty"`

	// Deliverable describes the actual artifact/result produced by the tool,
	// independent from LLM context or user-facing phrasing. Use this for durable
	// task state and follow-up ownership; Completion is kept as the legacy
	// child-run handoff shape and is mirrored into Deliverable when possible.
	Deliverable *DeliverableResult `json:"deliverable,omitempty"`

	// Messages holds the ephemeral session history after execution.
	// Only populated by SubTurn executions; used by evaluator_optimizer
	// to carry stateful worker context across evaluation iterations.
	Messages []providers.Message `json:"-"`

	// ArtifactTags exposes local artifact paths back to the LLM in a structured
	// form, e.g. "[file:/tmp/example.png]". This is used when a tool produced a
	// reusable local artifact but did not deliver it to the user yet.
	ArtifactTags []string `json:"artifact_tags,omitempty"`

	// ResponseHandled indicates that this tool execution already satisfied the
	// user's request at the channel/output level, so the agent loop can stop
	// without a follow-up assistant response.
	ResponseHandled bool `json:"response_handled,omitempty"`

	// ImmediateDelivery asks the agent loop to deliver this tool result to the
	// user immediately while still continuing the turn. This is the pipeline
	// equivalent of the message tool's direct-send behavior for tools that
	// produce MediaStore refs or other ToolResult outputs.
	ImmediateDelivery bool `json:"immediate_delivery,omitempty"`

	// DeliveryIntent is the canonical output ownership policy for this tool
	// result. Legacy ResponseHandled/ImmediateDelivery fields remain as
	// compatibility projections for older tools and callers.
	DeliveryIntent DeliveryIntent `json:"delivery_intent,omitempty"`

	// Outbound carries a fully resolved chat output for the runtime delivery
	// coordinator. Tools should prefer this over sending directly.
	Outbound *OutboundDelivery `json:"outbound,omitempty"`

	// CommitOutbound durably records that the prepared outbound attempt is
	// being scheduled. It runs only after the tool result is journaled and
	// immediately before synchronous delivery. It is never model-visible.
	CommitOutbound func(context.Context) error `json:"-"`

	// WriteAudit records verified write-side effects performed by this tool.
	// Agents should use this as the source of truth for claims like "saved",
	// "updated", or "created"; prose in ForLLM/ForUser is only descriptive.
	WriteAudit []WriteAuditEntry `json:"write_audit,omitempty"`

	// Suspension asks the runtime to durably pause this tool call for human
	// input. It is control-plane state, not model-visible tool output. The
	// runtime must enrich it with trusted route and origin data before use.
	Suspension *interactions.SuspensionRequest `json:"-"`

	// SuspensionResolution performs a bounded domain transition when the
	// durable interaction is answered, times out, is canceled, or fails. It is
	// process-local; authoritative domain state must recover safely after a
	// restart without it.
	SuspensionResolution func(context.Context, interactions.Outcome) error `json:"-"`
}

type UsageInfo struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type WriteAuditEntry struct {
	Kind     string            `json:"kind"`
	Target   string            `json:"target"`
	Action   string            `json:"action"`
	Success  bool              `json:"success"`
	Tool     string            `json:"tool,omitempty"`
	Summary  string            `json:"summary,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}