integration

type ApplyOptions struct {
	// Preview reports every write as planned and writes nothing.
	Preview bool
	// Observe receives each result in order, as soon as it is known:
	// every document, then every skill directory. The caller narrates
	// from it, so its lines keep the order of the run. Nil is allowed.
	Observe func(OpResult)
	// SkillsLog receives the skill installer's own line for each skill
	// directory, in init's words. Nil discards it. A caller that prints
	// these lines skips the OpSkill results in Observe.
	SkillsLog io.Writer
}

type Capability string

type CapabilityInspection struct {
	Capability Capability `json:"capability"`
	// Supported is whether the descriptor declares the capability.
	Supported bool            `json:"supported"`
	State     CapabilityState `json:"state"`
	// Trust is the project's native trust state for this capability.
	Trust TrustState `json:"trust"`
	// Verification is the native compatibility evidence.
	Verification VerificationEvidence `json:"verification"`
	// Detail is a bounded, sanitized explanation for narration. It is
	// supplemental: consumers must read the typed fields, never parse it.
	// It never names the client: the consumer adds the client label.
	Detail string `json:"detail,omitempty"`
	// Action is the command or edit that changes the state, from the
	// same adapter knowledge that installs the artifact; empty when
	// nothing needs to change. init, doctor, and status print it as
	// the corrective action, so the three never disagree on the fix.
	Action string `json:"action,omitempty"`
}

type CapabilityState int

type Client struct {
	// ID is the stable identifier used by `--client` and by `agent.cli`
	// in .seamark/config.yaml: lowercase letters, digits, and hyphens.
	ID string
	// Name is the display name for narration ("Claude Code").
	Name string
	// SkillDirs lists the repository-relative, slash-separated skill
	// directories the client reads. A directory can be shared between
	// clients; the destination identity is the directory, not the client.
	// A non-empty list declares CapabilitySkills; there is no separate
	// flag that could disagree with the list.
	SkillDirs []string
	// Setup plans native configuration. Nil when the client has none.
	Setup SetupAdapter
	// SetupOps declares the optional operations Setup can plan. The
	// registry rejects a declared operation when Setup is nil.
	SetupOps SetupSupport
	// Edits translates native edit events and advisory replies.
	Edits EditHooks
	// Commands translates native shell events and gate decisions.
	Commands CommandHooks
	// Resets translates native context-reset events.
	Resets ResetHooks
	// Invocation returns the one-shot inference command for a workspace
	// root. It is pure: no PATH lookup, no login, no process start.
	Invocation func(root string) (agent.CommandSpec, error)
}

type ClientPlan struct {
	Reads     []FileGuard
	Writes    []FileWrite
	Kept      []FileKeep
	GateHooks []GateHook
	Findings  []Finding
}

type ClientSetup struct {
	ClientID string
	// Skills installs the client's skill directories.
	Skills bool
	// Hooks installs the client's lifecycle hooks.
	Hooks bool
	// RegisterMCP registers the seamark MCP server natively.
	RegisterMCP bool
	// ApproveTools adds the exact per-tool grants (opt-in).
	ApproveTools bool
	// GateMode is warn or enforce; empty preserves the installed mode.
	GateMode string
	// CheckHookSources makes the adapter inspect the client's other hook
	// sources for seamark handlers. An init run without --client leaves
	// it off: that form never read those files, and it must stay as it
	// was.
	CheckHookSources bool
}

type CommandEvent struct {
	EventMeta
	Command string
}

type CommandHooks interface {
	DecodeCommand(payload []byte) (CommandEvent, error)
	EncodeDecision(decision *gate.Decision) (HookReply, error)
	EncodeFailure(err error) HookReply
}

type Document struct {
	// Path is repository-relative and slash-separated.
	Path string
	// CreateOnly marks a starter file. An existing path is kept without a
	// read, whatever it is; Compose then only supplies the new content.
	CreateOnly bool
	// Compose returns the complete file. exists is false for an absent
	// file; existing is then nil.
	Compose func(existing []byte, exists bool) ([]byte, error)
	// Detail says what the write adds, for narration. KeptDetail says
	// why an unchanged file needs nothing.
	Detail     string
	KeptDetail string
	// Narrate replaces the generic line when set.
	Narrate Narrator
}

type EditEvent struct {
	EventMeta
	// Paths lists the affected paths as the client reported them. The
	// shared normalization resolves them against CWD and the workspace,
	// preserving order and removing duplicates.
	Paths []string
}

type EditHooks interface {
	DecodeEdit(payload []byte) (EditEvent, error)
	EncodeAdvice(text string) (HookReply, error)
	AdviceMechanism() string
}

type EventMeta struct {
	// SessionID is the client's session identifier, useful for audit
	// even when it is insufficient for suppression.
	SessionID string
	// MatchID identifies the native tool call (Claude tool_use_id, Codex
	// tool_use_id) so repeated matches join in the audit log.
	MatchID string
	// NativeTool is the client's tool name as reported ("Edit",
	// "apply_patch"), recorded for statistics.
	NativeTool string
	// CWD is the event working directory, used to resolve relative paths
	// inside the workspace.
	CWD string
	// Context is the receiving context, or nil when the adapter cannot
	// identify one. Nil disables once-per-context suppression.
	Context *ReceivingContext
}

type FileGuard struct {
	Path   string
	Kind   GuardKind
	Exists bool
	// Linked is the first component of the path that is a symbolic link,
	// or empty. Setup never writes a linked path.
	Linked string
	SHA256 [32]byte
	Mode   fs.FileMode
	// Denied is true when this user may not write the existing file,
	// although the owner write bit can be set. An access control list or
	// another owner causes it. A plain write fails on such a file, so
	// setup never replaces it.
	Denied bool
}

type FileKeep struct {
	Path      string
	Consumers []string
	// Detail says why nothing changes, for narration.
	Detail string
	// Narrate replaces the generic line when set.
	Narrate Narrator
}

type FileWrite struct {
	Path  string
	After []byte
	// Mode is the permission for a new file. An existing file keeps its
	// own permission. Zero means 0644.
	Mode      fs.FileMode
	Consumers []string
	// Detail says what the write adds, for narration. It must never hold
	// file content: a preview must not print native configuration.
	Detail string
	// Narrate replaces the generic line when set.
	Narrate Narrator
}

type Finding struct {
	Level FindingLevel `json:"level"`
	// Path is the repository-relative document the finding is about.
	Path   string `json:"path,omitempty"`
	Reason string `json:"reason"`
	// Action is the command or edit that resolves the finding; empty
	// when nothing needs to change.
	Action string `json:"action,omitempty"`
}

type FindingLevel int

type GateEffect int

type GateHook struct {
	// ClientID is filled by the coordinator.
	ClientID string
	// Path is the document that holds the hook, repository-relative.
	Path string
	// Mode is warn, enforce, or GateModeReportOnly. Only a hook that
	// setup does not manage can be report-only.
	Mode string
	// Managed is true for the hook setup installs and updates. False
	// means another source, which setup never edits.
	Managed bool
	// Uncertain is true when the reader cannot tell whether the
	// definition runs the gate. For example, another program gets the
	// gate command as its arguments. Mode is then the mode the
	// definition has when it runs.
	Uncertain bool
}

type GateSummary struct {
	// Enforce lists the hooks that carry --enforce. A verdict of theirs
	// blocks, whatever the policy file says.
	Enforce []string
	// Warn lists the hooks that follow the policy file. A verdict of
	// theirs blocks only when the policy file enforces.
	Warn []string
	// ReportOnly lists the hooks that discard their exit status. No
	// verdict of theirs blocks, whatever --enforce or the policy file
	// says.
	ReportOnly []string
	// Possible lists the definitions that can run a gate hook, where the
	// reader cannot tell whether they do. What they do is unknown, not
	// nothing.
	Possible []string
	// Unreadable lists the hook documents that cannot be read. What
	// their hooks do is unknown, not nothing.
	Unreadable []string
}

type GuardKind int

type HookReply struct {
	Stdout   []byte
	Stderr   []byte
	ExitCode int
}

type Inspection struct {
	ClientID string `json:"client"`
	// Name is the display name, filled by the registry.
	Name string `json:"name,omitempty"`
	// Declared lists every capability the descriptor declares, filled by
	// the registry. It covers the capabilities without project
	// configuration too (setup, invocation), which Capabilities omits.
	Declared []Capability `json:"declared,omitempty"`
	// Setup is what setup installs for the client, filled by the
	// registry, so narration can tell a missing hook from one that setup
	// never installs.
	Setup        SetupSupport           `json:"setup"`
	Capabilities []CapabilityInspection `json:"capabilities"`
	// GateMode is the mode the client's gate hooks run in, from every
	// definition that certainly runs one, managed or not. It is enforce
	// when any enforces, and warn when any follows the policy file. It is
	// GateModeReportOnly when each one discards its exit status. It is
	// empty when none runs or the document cannot be read. One enforcing
	// definition blocks whatever the managed hook says. The repository
	// policy file can still enforce on top of a warn hook, and never on
	// top of a report-only one.
	GateMode string `json:"gate_mode,omitempty"`
	// PossibleGateMode is the mode of the definitions that can run a
	// gate hook, by the rule of GateMode. The reader cannot tell whether
	// they do. It is empty without such a definition. A reader must not
	// take it for GateMode. A gate that may enforce is not one that
	// enforces, and not one that never blocks.
	PossibleGateMode string `json:"possible_gate_mode,omitempty"`
	// ManagedGateMode is the mode of the hook setup manages, or empty.
	// Setup keeps it when no mode is requested; it never reads a mode
	// from a definition it does not own.
	ManagedGateMode string `json:"managed_gate_mode,omitempty"`
	// HookDocumentError is the reason when the hook document that setup
	// manages cannot be read, and empty otherwise. The reason names the
	// document and is sanitized. The hook entries carry the same reason
	// in their detail, after the word "unreadable". Status repeats it in
	// its legacy gate_hook_error field, so no consumer reads it back from
	// the detail.
	HookDocumentError string `json:"hook_document_error,omitempty"`
	// Findings name the limitations and the duplicate handlers the
	// adapter sees: trust it cannot read, a receiving context it does not
	// identify, a second source that runs the same hook.
	Findings []Finding `json:"findings,omitempty"`
}

type Narrator func(w io.Writer, status OpStatus)

type OpKind int

type OpResult struct {
	Kind OpKind
	// Path is the document, or the skill directory, repository-relative.
	Path   string
	Status OpStatus
	// Created is true when the path did not exist before the run.
	Created   bool
	Detail    string
	Consumers []string
	// Narrate is the planner's narrator for the operation; nil when the
	// generic line is enough.
	Narrate Narrator
	// Err is the cause of OpFailed; nil otherwise.
	Err error
}

type OpStatus int

type ReceivingContext struct {
	// ID is the client-native identity, kept in memory only. Persisted
	// state stores a repository-scoped digest, never the raw value.
	ID string
	// Resettable is true when the adapter's compatibility checks
	// established that a reset event reaches this exact context.
	Resettable bool
}

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

type ResetEvent struct {
	Context ReceivingContext
}

type ResetHooks interface {
	DecodeReset(payload []byte) (ResetEvent, error)
}

type SetupAdapter interface {
	// Inspect reports the current configuration state without writing.
	Inspect(root string) Inspection
	// ManagedGateMode returns the mode of the gate hook that setup
	// manages: warn, enforce, or "" when none runs or the adapter has no
	// gate hook. It reads the managed hook document alone. init calls it
	// before it plans, and the plan reads every document again, so a full
	// Inspect here doubles the reads. The value must equal Inspect's
	// ManagedGateMode and the mode that Plan keeps, so the adapter reads
	// all three through one helper.
	ManagedGateMode(root string) string
	// Plan composes every edit to the client's native documents for one
	// request. Each native document appears at most once in Writes.
	Plan(root, binary string, request ClientSetup) (ClientPlan, error)
}

type SetupPlan struct {
	// Root is the workspace the plan was made for.
	Root string
	// Reads guards every input. Its order is the document order of the
	// run: common documents first, then each client in registry order.
	Reads  []FileGuard
	Writes []FileWrite
	Kept   []FileKeep
	Skills []skills.Entry
	// SkillGuards is parallel to Skills: one guard per entry.
	SkillGuards  []SkillGuard
	Destinations []SkillDestination
	// GateHooks lists the gate hooks the selected clients run after apply.
	GateHooks []GateHook
	Findings  []Finding
}

type SetupRequest struct {
	Root    string
	Binary  string
	Clients []ClientSetup
	// Common lists the client-independent documents of the run, such as
	// the .seamark scaffolds and the .gitignore entries. The caller owns
	// their content; the coordinator guards, plans, and writes them with
	// the client documents, so one preflight covers every write.
	Common []Document
}

type SetupResult struct {
	Ops    []OpResult
	Skills []OpResult
}

type SetupSupport struct {
	// Hooks means the adapter can install the client's lifecycle hooks.
	// It is a setup operation, not a capability: the codecs that handle
	// the hook events are declared through Edits, Commands, and Resets.
	Hooks bool `json:"hooks"`
	// GateHook means the installed hooks include the command gate, so a
	// gate mode applies to the client. A client can install lesson hooks
	// and no gate hook, and init must then print no gate mode for it.
	GateHook bool `json:"gate_hook"`
	// ResetHook means the installed hooks include the context reset. A
	// client whose reset has no observable effect installs none, and
	// diagnostics must then not call the absent hook missing.
	ResetHook bool `json:"reset_hook"`
	// RegisterMCP means the adapter can register the seamark MCP server.
	RegisterMCP bool `json:"register_mcp"`
	// ApproveTools means the adapter can add the exact per-tool grants.
	// It is independent of RegisterMCP.
	ApproveTools bool `json:"approve_tools"`
}

type SkillDestination struct {
	Dir       string
	Consumers []string
}

type SkillGuard struct {
	// Rel is the skill directory, repository-relative.
	Rel    string
	Digest [32]byte
}

type TrustState int

type Verification int

type VerificationEvidence struct {
	Level Verification `json:"level"`
	// ClientVersion is the client version the recorded check ran against.
	ClientVersion string `json:"client_version,omitempty"`
	// Surface names the native surface the check exercised, for example
	// "PreToolUse apply_patch".
	Surface string `json:"surface,omitempty"`
}

type WritePreview struct {
	// Path is the repository-relative path of the write.
	Path string
	// Created is true when the file does not exist yet.
	Created bool
	// Diff is a unified diff with explicit "+" and "-" line markers.
	Diff string
	// Added and Removed count the changed lines.
	Added, Removed int
	// Consumers names the clients that contribute to the write; empty
	// for shared Seamark documents.
	Consumers []string
	// Detail is the planner's one-line description of the write.
	Detail string
	// Stale is true when the file changed after planning, so the plan
	// can no longer apply.
	Stale bool
	// Err holds a read failure of the current file.
	Err error
}