jinn

type Classification ¶ added in v0.6.0

type Classification string

Classification describes how a shell exit code should be interpreted by the calling LLM. Expected-nonzero exits are semantic signals, not failures.

const (
	// ClassSuccess means exit 0 — command completed normally.
	ClassSuccess Classification = "success"
	// ClassExpectedNonzero means a non-zero exit that is a semantic signal
	// (e.g., grep exit 1 = no matches). The LLM should NOT retry.
	ClassExpectedNonzero Classification = "expected_nonzero"
	// ClassError means an unexpected non-zero exit indicating failure.
	ClassError Classification = "error"
	// ClassTimeout means the command exceeded its time limit (exit 124).
	ClassTimeout Classification = "timeout"
	// ClassSignal means the process was killed by a signal.
	ClassSignal Classification = "signal"
)

type Engine ¶

type Engine struct {
	// contains filtered or unexported fields
}

Engine is a sandboxed tool executor bound to a working directory.

func New(workDir string) *Engine

func (e *Engine) Dispatch(ctx context.Context, tool string, args map[string]interface{}) (string, map[string]string, error)

type ErrWithSuggestion ¶ added in v0.6.0

type ErrWithSuggestion struct {
	Err        error
	Suggestion string
}

ErrWithSuggestion wraps an error with a one-sentence next-step suggestion for the calling LLM. Suggestions follow the style guide below so future maintainers add new suggestions consistently.

Style guide for suggestion strings:

• Imperative mood ("use list_dir", "verify the path", "check ownership")
• One sentence only — no hedging words ("might", "perhaps", "try to")
• Name the specific tool or parameter the agent should use next
• No trailing period

func (e *ErrWithSuggestion) Error() string

func (e *ErrWithSuggestion) Unwrap() error

type Request ¶

type Request struct {
	Tool string                 `json:"tool"`
	Args map[string]interface{} `json:"args"`
}

Request is the one-shot tool invocation envelope.

type Response ¶

type Response struct {
	OK             bool   `json:"ok"`
	Result         string `json:"result,omitempty"`
	Error          string `json:"error,omitempty"`
	Suggestion     string `json:"suggestion,omitempty"`
	Classification string `json:"classification,omitempty"` // exit-code class: "success", "expected_nonzero", "error", "timeout", "signal"
	Risk           string `json:"risk,omitempty"`           // pre-execution risk: "safe", "caution", "dangerous" — only set by run_shell
}

Response is the one-shot tool result envelope.

type RiskLevel ¶ added in v0.6.0

type RiskLevel int

RiskLevel describes how dangerous a shell command is to execute.

const (
	// RiskSafe — read-only, no side effects visible outside stdout.
	RiskSafe RiskLevel = iota
	// RiskCaution — modifies state, but generally recoverable.
	RiskCaution
	// RiskDangerous — destructive or irreversible.
	RiskDangerous
)

func ClassifyCommand(cmdline string) (RiskLevel, string)

func (r RiskLevel) String() string