Documentation
¶
Overview ¶
Package backend exposes K-brain's canonical session and Agent runtime over HTTP.
Index ¶
- Constants
- type BackendHook
- type BackendHookRunner
- type CronApplyInput
- type CronApplyResponse
- type CronHTTPRequest
- type CronModelRef
- type CronOperation
- type CronRunNowResponse
- type CronRunRecord
- type CronSnapshot
- type CronTask
- type Factory
- type HookOperation
- type HookRequest
- type HookStore
- type HookType
- type HooksApplyInput
- type HooksApplyResponse
- type HooksSnapshot
- type ImageAssets
- type ImageAuthorization
- type ImageDelegationConfig
- type ImageDelegationKey
- type ImageDependencyChecker
- type ImageJobs
- type ImageModule
- type ImageScopeResolver
- type ImageSettingsManager
- func (m *ImageSettingsManager) CheckProviderImageTarget(ctx context.Context, scope imaging.Scope, target imaging.TargetSnapshot) error
- func (m *ImageSettingsManager) ImageSettings(scope imaging.Scope) (imaging.ImageSettings, error)
- func (m *ImageSettingsManager) ListImageTargets(scope imaging.Scope) ([]imaging.ImageTarget, error)
- func (m *ImageSettingsManager) ResolveImageConnection(ctx context.Context, scope imaging.Scope, id string) (ResolvedImageConnection, error)
- func (m *ImageSettingsManager) ResolveImageTargetConnection(ctx context.Context, scope imaging.Scope, target imaging.TargetSnapshot) (ResolvedImageConnection, error)
- func (m *ImageSettingsManager) ResolveTarget(ctx context.Context, scope imaging.Scope, id string) (imaging.TargetSnapshot, error)
- func (m *ImageSettingsManager) UpdateImageSettings(ctx context.Context, scope imaging.Scope, update imaging.ImageSettingsUpdate) (imaging.ImageSettings, error)
- func (m *ImageSettingsManager) VerifyImageTarget(ctx context.Context, scope imaging.Scope, expectedRevision uint64, ...) (imaging.ImageSettings, error)
- func (m *ImageSettingsManager) WithImageTarget(ctx context.Context, scope imaging.Scope, id string, ...) error
- func (m *ImageSettingsManager) WriteImageSecret(ctx context.Context, scope imaging.Scope, input imaging.ImageSecretInput) (imaging.ImageSecretResult, error)
- type ImageSettingsOptions
- type ImageVerificationManager
- func (v *ImageVerificationManager) CheckExecution(ctx context.Context, scope imaging.Scope, target imaging.TargetSnapshot) error
- func (v *ImageVerificationManager) Get(ctx context.Context, scope imaging.Scope, targetID, id string) (imaging.VerificationReceipt, error)
- func (v *ImageVerificationManager) Start(ctx context.Context, scope imaging.Scope, id, key string, ...) (imaging.VerificationReceipt, bool, error)
- type MemoryRuntimeFactory
- type Options
- type ProviderUsageResult
- type ProviderUsageService
- type ResolvedImageConnection
- type Server
- type SettingsStore
- type UsageData
Constants ¶
const ImageDelegationHeader = "X-Kbrain-Image-Delegation"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BackendHook ¶
type BackendHook struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Event string `json:"event"`
Enabled bool `json:"enabled"`
Type HookType `json:"type"`
Script string `json:"script,omitempty"`
Requests []HookRequest `json:"requests,omitempty"`
TimeoutMS int `json:"timeoutMs,omitempty"`
}
type BackendHookRunner ¶
type BackendHookRunner struct {
// contains filtered or unexported fields
}
func NewBackendHookRunner ¶
func NewBackendHookRunner(store *HookStore) *BackendHookRunner
func (*BackendHookRunner) Scope ¶
func (r *BackendHookRunner) Scope(ctx context.Context, conversationID, runID, cwd string, warn func(BackendHook, string, error)) func(string)
Scope snapshots configuration once; event replay never invokes this callback.
type CronApplyInput ¶
type CronApplyInput struct {
BaseRevision uint64 `json:"baseRevision"`
Ops []CronOperation `json:"ops"`
}
type CronApplyResponse ¶
type CronApplyResponse struct {
Status string `json:"status"`
Cron CronSnapshot `json:"cron"`
}
type CronHTTPRequest ¶
type CronModelRef ¶
type CronOperation ¶
type CronRunNowResponse ¶
type CronRunRecord ¶
type CronRunRecord struct {
Delivered bool `json:"delivered,omitempty"`
SessionID string `json:"sessionId,omitempty"`
RunID string `json:"runId,omitempty"`
Counted bool `json:"counted"`
ID string `json:"id"`
TaskID string `json:"taskId"`
State string `json:"state"`
Success bool `json:"success"`
StartedAt int64 `json:"startedAt"`
FinishedAt *int64 `json:"finishedAt,omitempty"`
DurationMs uint64 `json:"durationMs"`
ExitCode *int `json:"exitCode,omitempty"`
Output string `json:"output"`
TerminationReason string `json:"terminationReason,omitempty"`
}
type CronSnapshot ¶
type CronTask ¶
type CronTask struct {
ID string `json:"id"`
Loop *loopSchedule `json:"loop,omitempty"`
// SessionID binds prompt tasks to one durable canonical conversation.
SessionID string `json:"sessionId,omitempty"`
Name string `json:"name"`
Description string `json:"description"`
Cron string `json:"cron"`
Enabled bool `json:"enabled"`
RemainingExecutions *uint64 `json:"remainingExecutions,omitempty"`
TimeoutSeconds uint64 `json:"timeoutSeconds"`
Type string `json:"type"`
Script string `json:"script,omitempty"`
Requests []CronHTTPRequest `json:"requests,omitempty"`
Prompt string `json:"prompt,omitempty"`
SelectedModel *CronModelRef `json:"selectedModel,omitempty"`
Reasoning string `json:"reasoning,omitempty"`
Workdir string `json:"workdir,omitempty"`
LastError string `json:"lastError,omitempty"`
// MemoryOff records that a user wrote the prompt while memory was off; its runs stay
// out of memory extraction. Backend-owned: set from the switch, never cleared.
MemoryOff bool `json:"memoryOff,omitempty"`
}
type HookOperation ¶
type HookRequest ¶
type HookStore ¶
type HookStore struct {
// contains filtered or unexported fields
}
func NewHookStore ¶
func (*HookStore) Apply ¶
func (s *HookStore) Apply(in HooksApplyInput) (HooksApplyResponse, error)
func (*HookStore) Snapshot ¶
func (s *HookStore) Snapshot() HooksSnapshot
type HooksApplyInput ¶
type HooksApplyInput struct {
BaseRevision uint64 `json:"baseRevision"`
Ops []HookOperation `json:"ops"`
}
type HooksApplyResponse ¶
type HooksApplyResponse struct {
Status string `json:"status"`
Hooks HooksSnapshot `json:"hooks"`
}
type HooksSnapshot ¶
type HooksSnapshot struct {
Revision uint64 `json:"revision"`
Hooks []BackendHook `json:"hooks"`
}
type ImageAssets ¶ added in v0.107.6
type ImageAuthorization ¶ added in v0.107.6
ImageAuthorization is issued only by trusted server-side authentication. CanConfigure grants settings and secret management, independently of execution.
type ImageDelegationConfig ¶ added in v0.107.6
type ImageDelegationConfig struct {
BackendID string
Keys map[string]ImageDelegationKey
// Now is optional and primarily useful for deterministic tests.
Now func() time.Time
// MaxNonces bounds replay-cache memory. Saturation denies new requests;
// unexpired entries are never evicted to admit a replay.
MaxNonces int
}
type ImageDelegationKey ¶ added in v0.107.6
ImageDelegationKey is server-owned trust configuration. AllowConfigure is an additional ceiling on the signed configuration grant.
type ImageDependencyChecker ¶ added in v0.107.6
type ImageDependencyChecker interface {
ImageDependenciesInUse(context.Context, imaging.Scope, []string, []string) (bool, error)
}
ImageDependencyChecker is called under SettingsStore.mu. The job service must serialize job acceptance with this check and must not re-enter SettingsStore. Include queued, running, saving, cancelling and unresolved accepted jobs.
type ImageJobs ¶ added in v0.107.6
type ImageJobs interface {
CreateJob(context.Context, imaging.Scope, string, imaging.CreateJobRequest) (imaging.ImageJob, bool, error)
GetJob(context.Context, imaging.Scope, string) (imaging.ImageJob, error)
ListJobs(context.Context, imaging.Scope, string, imaging.PageRequest) (imaging.Page[imaging.ImageJob], error)
CancelJob(context.Context, imaging.Scope, string) (imaging.ImageJob, error)
ReadEvents(context.Context, imaging.Scope, string, uint64, int) ([]imaging.ImageEvent, error)
}
ImageJobs is the public service contract. Execution and recovery belong to imaging.Service; HTTP requests never own the lifetime of accepted jobs.
type ImageModule ¶ added in v0.107.6
type ImageModule struct {
Verification *ImageVerificationManager
Settings *ImageSettingsManager
Store *imaging.Store
Assets ImageAssets
Jobs ImageJobs
AllowLocalImageScope bool
ResolveScope ImageScopeResolver
}
ImageModule dependencies are assembled by the process owner. Store must be the same store used by Jobs so snapshots and event positions are atomic. The process owner starts/recovers and closes Jobs before closing Assets/Store.
type ImageScopeResolver ¶ added in v0.107.6
type ImageScopeResolver func(*http.Request) (ImageAuthorization, error)
ImageScopeResolver verifies any delegated identity and its configuration grant. It runs only after the configured backend Bearer token has been verified.
func NewImageDelegationResolver ¶ added in v0.107.6
func NewImageDelegationResolver(cfg ImageDelegationConfig) (ImageScopeResolver, error)
NewImageDelegationResolver returns ImageModule.ResolveScope. The module calls it only after authenticating the backend bearer. No owner/backend/header fallback exists. Trust keys are copied and backend identity is pinned here.
Replay state belongs to one process: deployments must use one verifier per backend, or a shared atomic nonce store before load balancing. On restart, rotate trust keys (or wait >60 seconds before accepting the old keys). This does not make the local-only settings manager multi-tenant.
type ImageSettingsManager ¶ added in v0.107.6
type ImageSettingsManager struct {
// contains filtered or unexported fields
}
ImageSettingsManager shares the settings store's one configuration lock. Construct one manager per store, with an explicit private secret file path. Only {OwnerID:"local", BackendID:"local"} is supported until trusted owner delegation and per-owner settings storage are implemented.
func NewImageSettingsManager ¶ added in v0.107.6
func NewImageSettingsManager(store *SettingsStore, secretPath string, opts ImageSettingsOptions) (*ImageSettingsManager, error)
func (*ImageSettingsManager) CheckProviderImageTarget ¶ added in v0.107.6
func (m *ImageSettingsManager) CheckProviderImageTarget(ctx context.Context, scope imaging.Scope, target imaging.TargetSnapshot) error
CheckProviderImageTarget fences queued/recovered execution against config changes.
func (*ImageSettingsManager) ImageSettings ¶ added in v0.107.6
func (m *ImageSettingsManager) ImageSettings(scope imaging.Scope) (imaging.ImageSettings, error)
func (*ImageSettingsManager) ListImageTargets ¶ added in v0.107.6
func (m *ImageSettingsManager) ListImageTargets(scope imaging.Scope) ([]imaging.ImageTarget, error)
ListImageTargets merges legacy targets with provider-derived targets without persisting derived entries or exposing provider secrets/endpoints/headers.
func (*ImageSettingsManager) ResolveImageConnection ¶ added in v0.107.6
func (m *ImageSettingsManager) ResolveImageConnection(ctx context.Context, scope imaging.Scope, id string) (ResolvedImageConnection, error)
func (*ImageSettingsManager) ResolveImageTargetConnection ¶ added in v0.107.6
func (m *ImageSettingsManager) ResolveImageTargetConnection(ctx context.Context, scope imaging.Scope, target imaging.TargetSnapshot) (ResolvedImageConnection, error)
ResolveImageTargetConnection binds the execution credential to the same current provider target checked at resolution, and checks again immediately before send.
func (*ImageSettingsManager) ResolveTarget ¶ added in v0.107.6
func (m *ImageSettingsManager) ResolveTarget(ctx context.Context, scope imaging.Scope, id string) (imaging.TargetSnapshot, error)
ResolveTarget implements imaging.Registry for trusted local execution.
func (*ImageSettingsManager) UpdateImageSettings ¶ added in v0.107.6
func (m *ImageSettingsManager) UpdateImageSettings(ctx context.Context, scope imaging.Scope, update imaging.ImageSettingsUpdate) (imaging.ImageSettings, error)
func (*ImageSettingsManager) VerifyImageTarget ¶ added in v0.107.6
func (m *ImageSettingsManager) VerifyImageTarget(ctx context.Context, scope imaging.Scope, expectedRevision uint64, targetID string) (imaging.ImageSettings, error)
VerifyImageTarget is retained as a fail-closed compatibility shim. Synchronous callbacks cannot certify durable outputs or preserve submission idempotency. Use ImageVerificationManager.Start/Get with explicit consent instead.
func (*ImageSettingsManager) WithImageTarget ¶ added in v0.107.6
func (m *ImageSettingsManager) WithImageTarget(ctx context.Context, scope imaging.Scope, id string, accept func(imaging.TargetSnapshot) error) error
WithImageTarget serializes durable job acceptance with configuration deletion. The service callback must persist its dependency before returning and must not call back into this manager or SettingsStore. Both this callback and the dependency checker acquire service locks AFTER the settings lock.
func (*ImageSettingsManager) WriteImageSecret ¶ added in v0.107.6
func (m *ImageSettingsManager) WriteImageSecret(ctx context.Context, scope imaging.Scope, input imaging.ImageSecretInput) (imaging.ImageSecretResult, error)
WriteImageSecret stores a literal and returns its opaque reference. The caller attaches that reference with UpdateImageSettings; no config save spans two files. Rewriting a purpose rotates its value; an empty value revokes it.
type ImageSettingsOptions ¶ added in v0.107.6
type ImageSettingsOptions struct {
Dependencies ImageDependencyChecker
// Only trusted provider configuration is passed to this resolver. HTTP secret
// input is always stored literally and never reaches this function.
ResolveProviderSecret func(context.Context, string) (string, error)
// Deprecated: ignored. Only durable successful verification jobs may issue evidence.
VerifyTarget func(context.Context, imaging.Scope, imaging.TargetSnapshot) (imaging.TargetVerification, error)
}
type ImageVerificationManager ¶ added in v0.107.6
type ImageVerificationManager struct {
// contains filtered or unexported fields
}
func NewImageVerificationManager ¶ added in v0.107.6
func NewImageVerificationManager(settings *ImageSettingsManager, service *imaging.Service, assets ImageAssets) *ImageVerificationManager
func (*ImageVerificationManager) CheckExecution ¶ added in v0.107.6
func (v *ImageVerificationManager) CheckExecution(ctx context.Context, scope imaging.Scope, target imaging.TargetSnapshot) error
CheckExecution prevents a queued verification from using a changed binding. Finalization independently checks again after persisted output is available.
func (*ImageVerificationManager) Get ¶ added in v0.107.6
func (v *ImageVerificationManager) Get(ctx context.Context, scope imaging.Scope, targetID, id string) (imaging.VerificationReceipt, error)
Get never submits work. Finalization is idempotent and settings publication is atomic. A failed settings save can be retried without touching the upstream.
func (*ImageVerificationManager) Start ¶ added in v0.107.6
func (v *ImageVerificationManager) Start(ctx context.Context, scope imaging.Scope, id, key string, input imaging.VerifyTargetRequest) (imaging.VerificationReceipt, bool, error)
type MemoryRuntimeFactory ¶
type Options ¶
type Options struct {
Image *ImageModule
Store *session.Store
Factory Factory
EventDir string
Token string
Models []protocol.ModelRef
DefaultCWD string
FilesystemRoots []string
Settings *SettingsStore
Prompts *resources.PromptStore
MemoryRoot string
MemoryStore *memory.Store
MemoryRuntimeFactory MemoryRuntimeFactory
MemoryOrganizerInterval time.Duration
QuestionTimeout time.Duration
MCP *mcp.LiveManager
MCPCredentialBridge mcp.CredentialBridge
// Build identifies this binary in /v1/health; zero value reports a dev build.
Build protocol.Build
// PermissionRulesDir is the data directory holding user and project permission
// rules. Empty limits remembered rules to the session.
PermissionRulesDir string
// SandboxMasked lists directories hidden from commands of sandboxed runs in
// addition to the credential directories: the backend's own data and config.
SandboxMasked []string
}
type ProviderUsageResult ¶
type ProviderUsageService ¶
type ProviderUsageService struct {
// contains filtered or unexported fields
}
func NewProviderUsageService ¶
func NewProviderUsageService(settings *SettingsStore) *ProviderUsageService
func (*ProviderUsageService) ProviderExists ¶
func (s *ProviderUsageService) ProviderExists(id string) bool
func (*ProviderUsageService) Query ¶
func (s *ProviderUsageService) Query(ctx context.Context, providerID string, refresh bool) ProviderUsageResult
func (*ProviderUsageService) Test ¶
func (s *ProviderUsageService) Test(ctx context.Context, providerID string, draft usageConfig) ProviderUsageResult
type ResolvedImageConnection ¶ added in v0.107.6
type ResolvedImageConnection struct {
imaging.ResolvedConnection
BaseURL string `json:"-"`
AuthKind string `json:"-"`
SecretRefs map[string]string `json:"-"`
CustomHeaders map[string]string `json:"-"`
UseSystemProxy bool `json:"-"`
}
ResolvedImageConnection adds the execution endpoint to imaging's private injected client/resolver contract. Neither this object nor its embedded connection can be serialized into a public response.
func (ResolvedImageConnection) MarshalJSON ¶ added in v0.107.6
func (ResolvedImageConnection) MarshalJSON() ([]byte, error)
type SettingsStore ¶
type SettingsStore struct {
// contains filtered or unexported fields
}
SettingsStore publishes immutable snapshots only after persistence succeeds.
func NewSettingsStore ¶
func (*SettingsStore) Revision ¶
func (s *SettingsStore) Revision() uint64
func (*SettingsStore) Snapshot ¶
func (s *SettingsStore) Snapshot() *config.Config
type UsageData ¶
type UsageData struct {
PlanName string `json:"planName,omitempty"`
Extra string `json:"extra,omitempty"`
IsValid *bool `json:"isValid,omitempty"`
InvalidMessage string `json:"invalidMessage,omitempty"`
Total *float64 `json:"total,omitempty"`
Used *float64 `json:"used,omitempty"`
Remaining *float64 `json:"remaining,omitempty"`
Unit string `json:"unit,omitempty"`
}
Source Files
¶
- ai_approval.go
- checkpoint.go
- checkpoint_import.go
- client_tools.go
- command_note.go
- compact.go
- computer.go
- cron_canonical.go
- cron_handler.go
- cron_manager.go
- cron_store.go
- cron_tool.go
- cron_types.go
- cron_validate.go
- event_cache.go
- event_journal.go
- filesystem.go
- filesystem_mutate.go
- filesystem_rename_linux.go
- filesystem_rename_unix.go
- generate.go
- goal.go
- health.go
- history.go
- history_import.go
- history_import_repair.go
- history_search.go
- hooks.go
- hooks_handler.go
- image_assets.go
- image_delegation.go
- image_events.go
- image_jobs.go
- image_projects.go
- image_provider_targets.go
- image_routes.go
- image_settings.go
- image_verification.go
- loop_execution.go
- loop_schedule.go
- loops.go
- mcp.go
- memory.go
- memory_organizer.go
- network_proxy.go
- permission_rules.go
- planning.go
- planning_cron.go
- prompts.go
- provider_secrets.go
- provider_usage.go
- provider_usage_http.go
- questions.go
- queue.go
- queue_types.go
- run_lookup.go
- run_options.go
- run_progress.go
- run_sandbox.go
- run_start.go
- runtime_cache.go
- server.go
- session_sync.go
- settings.go
- settings_provider.go
- settings_public.go
- skill_read_roots.go
- skills_http.go
- slash_commands.go
- subagents.go
- terminal_http.go
- text.go
- tool_output.go
- trajectory.go
- trajectory_details.go
- trajectory_history.go
- trajectory_recording.go
- wake.go