builtin

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Classify 

func Classify(name string) (guarded, known bool)

Classify reports how a tool's output is treated, and whether anybody decided.

Exported for the test that guards a library upgrade: an unclassified tool is a decision nobody has made yet, not a safe default.

func CreateProposal 

func CreateProposal(s *store.Store, agentID, kind, title, summary, action, urgency string) (string, error)

CreateProposal writes a pending approval to the store and pushes an "Approval needed" notification to the phone. It is the single entry point for EVERYTHING that needs the operator's decision — the propose tool, the proactive WhatsApp proxy, and loops — so decisions always land in the approvals inbox (actionable: approve → execute), never as plain notifications.

func FromGoFunctionTool 

func FromGoFunctionTool(t ai.GoFunctionTool) tools.Tool

FromGoFunctionTool adapts one karma tool into KARMAX's registry.

func FromGoFunctionTools 

func FromGoFunctionTools(in []ai.GoFunctionTool) []tools.Tool

FromGoFunctionTools adapts a set, which is how a library publishes them.

func GuardUntrusted 

func GuardUntrusted(in []tools.Tool, source string) []tools.Tool

GuardUntrusted marks the tools in a set whose output is other people's words.

func Guarded 

func Guarded(t tools.Tool, source string) tools.Tool

Guarded marks a tool whose output is content KARMAX did not write.

Applied here rather than at each call site so a tool cannot arrive unguarded by being forgotten — the library will gain tools this repo never lists.

func NormalizeChatID 

func NormalizeChatID(s string) string

NormalizeChatID reduces a chat id or phone number to a comparable form.

func OperatorChats 

func OperatorChats() []string

OperatorChats is which chats are the operator's own rather than a third party's, from the environment the daemon was started with.

func PushAppNotification 

func PushAppNotification(s *store.Store, agentID, kind, title, body string)

PushAppNotification persists an app-feed notification and delivers it as a push. Reusable by non-tool code paths (e.g. the proactive "message sent" notice fired by the comms manager). Best-effort; never blocks the caller.

func SendExpoPush 

func SendExpoPush(s *store.Store, title, body, priority string, data map[string]any) (int, any, error)

SendExpoPush delivers a notification to every registered device via the Expo push service. Returns the device count and the raw Expo response. Shared by AppPushTool and the proposals subsystem.

Types

type ActivityTool 

type ActivityTool struct {
	Store   *store.Store
	AgentID string
}

ActivityTool reports what the operator has actually been building.

KARMAX already records every task it delegated to a coding harness — the description, whether it finished, and when. Nothing could read that back until now, which meant "what did I ship this week" had no answer that did not involve somebody scrolling through git.

It reports the DESCRIPTION of each task, never the output. Harness output is full of paths, hostnames and occasionally secrets, and this tool exists to feed things that summarise — including one that posts publicly.

func (*ActivityTool) Execute 

func (t *ActivityTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*ActivityTool) Manifest 

func (t *ActivityTool) Manifest() tools.ToolManifest

type AppPushTool 

type AppPushTool struct {
	Store   *store.Store
	AgentID string
}

AppPushTool sends a notification to the KARMAX phone app: it is persisted to the in-app notification feed AND delivered as an Expo push. The feed entry survives even if the push itself is missed or no device is registered.

func (*AppPushTool) Execute 

func (t *AppPushTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*AppPushTool) Manifest 

func (t *AppPushTool) Manifest() tools.ToolManifest

type CalendarAddTool 

type CalendarAddTool struct {
	Store   *store.Store
	AgentID string
}

CalendarAddTool enqueues a calendar event for the phone app to create on-device (EventKit). Additive and low-risk, so it runs directly without approval.

func (*CalendarAddTool) Execute 

func (t *CalendarAddTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*CalendarAddTool) Manifest 

func (t *CalendarAddTool) Manifest() tools.ToolManifest

type CapabilitiesTool 

type CapabilitiesTool struct {
	Registry *tools.Registry
	Store    *store.Store
	AgentID  string
	Loops    LoopLister
	// Held names the tools carried in full this turn, so the answer can
	// distinguish those from the ones needing tools.load first.
	Held []string
}

CapabilitiesTool answers "what can I do, and what is running".

func (*CapabilitiesTool) Execute 

func (t *CapabilitiesTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*CapabilitiesTool) Manifest 

func (t *CapabilitiesTool) Manifest() tools.ToolManifest

type ClaudeCodeTool 

type ClaudeCodeTool struct {
	Store   *store.Store
	AgentID string
	// Namespace is the memory namespace whose profile/entries are injected into
	// every call. Set per-agent in bindAgentTools; falls back to AgentID.
	Namespace string
	// MemoryMgr is what the injected memory is read from. Optional: a nil
	// manager just means the harness runs without the "possibly relevant
	// memory" block rather than with a stale one.
	MemoryMgr *memory.Manager
	// Publish delivers the result of a background delegation as an event. Nil
	// means background mode is unavailable and every call runs inline.
	Publish func(bus.Event) error
}

func (*ClaudeCodeTool) Execute 

func (t *ClaudeCodeTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*ClaudeCodeTool) Manifest 

func (t *ClaudeCodeTool) Manifest() tools.ToolManifest

type CodexTool 

type CodexTool struct {
	Store   *store.Store
	AgentID string
}

func (*CodexTool) Execute 

func (t *CodexTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*CodexTool) Manifest 

func (t *CodexTool) Manifest() tools.ToolManifest

type CommsSendTool 

type CommsSendTool struct {
	// SendFunc sends a message via the specified channel.
	// Accepts channelID, target, and content. Using a function type
	// avoids circular imports with the comms package.
	SendFunc func(channelID, target, content string) error
	// DefaultChannelID resolves the channel to use when the caller omits
	// channel_id (injected by the runtime; never a hardcoded name).
	DefaultChannelID func() (string, bool)
}

func (*CommsSendTool) Execute 

func (t *CommsSendTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*CommsSendTool) Manifest 

func (t *CommsSendTool) Manifest() tools.ToolManifest

type ContactAddTool 

type ContactAddTool struct {
	Store   *store.Store
	AgentID string
}

ContactAddTool enqueues a new phone contact for the app to create on-device (since WhatsApp only exposes a number). Additive and low-risk — no approval.

func (*ContactAddTool) Execute 

func (t *ContactAddTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*ContactAddTool) Manifest 

func (t *ContactAddTool) Manifest() tools.ToolManifest

type ContactUpdateTool 

type ContactUpdateTool struct {
	Store   *store.Store
	AgentID string
}

ContactUpdateTool renames an existing phone contact by number (upsert: if the number isn't saved yet, it's created). Useful for putting a name to a raw WhatsApp number or correcting a saved name. Additive/low-risk — no approval.

func (*ContactUpdateTool) Execute 

func (t *ContactUpdateTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*ContactUpdateTool) Manifest 

func (t *ContactUpdateTool) Manifest() tools.ToolManifest

type EmailTool 

type EmailTool struct{}

func (*EmailTool) Execute 

func (t *EmailTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*EmailTool) Manifest 

func (t *EmailTool) Manifest() tools.ToolManifest

type FileListTool 

type FileListTool struct{}

func (*FileListTool) Execute 

func (t *FileListTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*FileListTool) Manifest 

func (t *FileListTool) Manifest() tools.ToolManifest

type FileReadTool 

type FileReadTool struct{}

func (*FileReadTool) Execute 

func (t *FileReadTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*FileReadTool) Manifest 

func (t *FileReadTool) Manifest() tools.ToolManifest

type FileWriteTool 

type FileWriteTool struct{}

func (*FileWriteTool) Execute 

func (t *FileWriteTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*FileWriteTool) Manifest 

func (t *FileWriteTool) Manifest() tools.ToolManifest

type GogTool 

type GogTool struct {
	// Path to the gog binary. Empty resolves from PATH.
	Path string
	// DefaultAccount is impersonated when a call names none.
	DefaultAccount string
}

GogTool runs Google Workspace operations via the gog binary.

func (*GogTool) Execute 

func (t *GogTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*GogTool) Manifest 

func (t *GogTool) Manifest() tools.ToolManifest

type GoogleWorkspaceSchemaLookupTool 

type GoogleWorkspaceSchemaLookupTool struct {
	GWSPath string
}

func (*GoogleWorkspaceSchemaLookupTool) Execute 

func (t *GoogleWorkspaceSchemaLookupTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*GoogleWorkspaceSchemaLookupTool) Manifest 

func (t *GoogleWorkspaceSchemaLookupTool) Manifest() tools.ToolManifest

type GoogleWorkspaceTool 

type GoogleWorkspaceTool struct {
	GWSPath string
}

func (*GoogleWorkspaceTool) Execute 

func (t *GoogleWorkspaceTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*GoogleWorkspaceTool) Manifest 

func (t *GoogleWorkspaceTool) Manifest() tools.ToolManifest

type HTTPTool 

type HTTPTool struct{}

func (*HTTPTool) Execute 

func (t *HTTPTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*HTTPTool) Manifest 

func (t *HTTPTool) Manifest() tools.ToolManifest

type LoadToolTool 

type LoadToolTool struct {
	Registry *tools.Registry
	// Available lists the names the agent could lend. Nil means "anything in the
	// registry"; a non-nil list is the authority, so a tool the agent cannot bind
	// is never advertised as loadable.
	Available []string
}

LoadToolTool resolves a requested tool name against the registry so a request for something that does not exist fails immediately, with the real names, rather than being handed back to a model that will guess again.

func (*LoadToolTool) Execute 

func (t *LoadToolTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*LoadToolTool) Manifest 

func (t *LoadToolTool) Manifest() tools.ToolManifest

type LoopInfo 

type LoopInfo struct {
	Name     string `json:"name"`
	Triggers string `json:"triggers,omitempty"`
	Running  bool   `json:"running,omitempty"`
	Dark     bool   `json:"dark,omitempty"`
	LastErr  string `json:"last_error,omitempty"`
}

LoopInfo is one loop and its health.

type LoopLister 

type LoopLister func() []LoopInfo

LoopLister reports the loops this instance runs. Supplied by the runtime, which owns them.

type MemoryForgetTool 

type MemoryForgetTool struct {
	Store     *store.Store
	MemoryMgr *memory.Manager
	AgentID   string
}

MemoryForgetTool lets the agent curate its own long-term memory by removing a fact that is wrong, outdated, or superseded — making memory self-correcting rather than append-only.

func (*MemoryForgetTool) Execute 

func (t *MemoryForgetTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*MemoryForgetTool) Manifest 

func (t *MemoryForgetTool) Manifest() tools.ToolManifest

type MemoryIngestTool 

type MemoryIngestTool struct {
	Store     *store.Store
	MemoryMgr *memory.Manager // set per-agent at registration time
	AgentID   string
}

MemoryIngestTool lets the agent save important information to long-term memory with automatic deduplication against existing entries.

func (*MemoryIngestTool) Execute 

func (t *MemoryIngestTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*MemoryIngestTool) Manifest 

func (t *MemoryIngestTool) Manifest() tools.ToolManifest

type NotifyTool 

type NotifyTool struct{}

func (*NotifyTool) Execute 

func (t *NotifyTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*NotifyTool) Manifest 

func (t *NotifyTool) Manifest() tools.ToolManifest

type NtfyPushTool 

type NtfyPushTool struct {
	Server string // ntfy server, defaults to https://ntfy.sh
	Topic  string // default topic to publish to
}

NtfyPushTool sends a push notification to the operator's phone via ntfy. This is the lightweight "ping me" channel that works without a native app — the user just subscribes to the topic in the ntfy iOS app.

func (*NtfyPushTool) Execute 

func (t *NtfyPushTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*NtfyPushTool) Manifest 

func (t *NtfyPushTool) Manifest() tools.ToolManifest

type ProfileTool 

type ProfileTool struct {
	MemoryMgr *memory.Manager // set per-agent at registration time
	AgentID   string
}

ProfileTool lets the agent read and maintain a single curated Markdown document about the operator (ABOUT_ME.md). This is the agent's living, deduplicated understanding of who the user is — identity, projects, preferences, relationships, goals — distinct from the append-only memory log.

func (*ProfileTool) Execute 

func (t *ProfileTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*ProfileTool) Manifest 

func (t *ProfileTool) Manifest() tools.ToolManifest

type ProposeTool 

type ProposeTool struct {
	Store   *store.Store
	AgentID string
}

ProposeTool creates a human-in-the-loop approval request: KARMAX proposes an action, it appears in the operator's phone app (with a push), and only once they approve does the agent execute it. This is what makes "delegate anything with full access" safe.

func (*ProposeTool) Execute 

func (t *ProposeTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*ProposeTool) Manifest 

func (t *ProposeTool) Manifest() tools.ToolManifest

type RecipeTool 

type RecipeTool struct{}

RecipeTool lets the agent read, validate and write its own recipes.

func (*RecipeTool) Execute 

func (t *RecipeTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*RecipeTool) Manifest 

func (t *RecipeTool) Manifest() tools.ToolManifest

type ReminderAddTool 

type ReminderAddTool struct {
	Store   *store.Store
	AgentID string
}

ReminderAddTool enqueues an iOS Reminder for the app to create on-device.

func (*ReminderAddTool) Execute 

func (t *ReminderAddTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*ReminderAddTool) Manifest 

func (t *ReminderAddTool) Manifest() tools.ToolManifest

type ReviewResolveTool 

type ReviewResolveTool struct {
	Store     *store.Store
	MemoryMgr *memory.Manager
	AgentID   string
	Namespace string
}

ReviewResolveTool lets the agent close a staleness check-in ("is this still relevant?") using the operator's reply — from WhatsApp, the app, anywhere. The open reviews are injected into the agent's context (see agent.go); when the operator answers, the agent calls this to record the answer and apply the consequence to memory (keep / update / forget).

func (*ReviewResolveTool) Execute 

func (t *ReviewResolveTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*ReviewResolveTool) Manifest 

func (t *ReviewResolveTool) Manifest() tools.ToolManifest

type SchedulerTool 

type SchedulerTool struct {
	Scheduler *scheduler.Scheduler
	AgentID   string
}

func (*SchedulerTool) Execute 

func (t *SchedulerTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*SchedulerTool) Manifest 

func (t *SchedulerTool) Manifest() tools.ToolManifest

type SelfRemindTool 

type SelfRemindTool struct {
	Clock   *clock.Clock
	AgentID string
}

SelfRemindTool arms a durable timer that wakes the agent with a prompt.

func (*SelfRemindTool) Execute 

func (t *SelfRemindTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*SelfRemindTool) Manifest 

func (t *SelfRemindTool) Manifest() tools.ToolManifest

type ShellTool 

type ShellTool struct {
	AllowList []string
}

func (*ShellTool) Execute 

func (t *ShellTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*ShellTool) Manifest 

func (t *ShellTool) Manifest() tools.ToolManifest

type SpawnFunc 

type SpawnFunc func(ctx context.Context, childID, brief string) (string, error)

SpawnFunc runs a task on a fresh agent instance and returns its answer. The runtime supplies it; this package must not know how an agent is constructed.

type SubagentTool 

type SubagentTool struct {
	Store   *store.Store
	AgentID string
	Spawn   SpawnFunc
	Publish func(bus.Event) error
	// Depth is how deep this agent already is. A child spawned by a child
	// inherits depth+1, which is what stops a fan-out from recursing.
	Depth int
}

SubagentTool lets the agent run tasks on copies of itself.

func (*SubagentTool) Execute 

func (t *SubagentTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*SubagentTool) Manifest 

func (t *SubagentTool) Manifest() tools.ToolManifest

type WacliTool 

type WacliTool struct {
	WacliPath string
}

WacliTool gives the agent full control over the local WhatsApp bridge (wacli): managing the message webhook that feeds KARMAX, editing/deleting sent messages, reading receipts, controlling chat access (lock/unlock), inspecting chats/contacts/DND, and sending. It runs the wacli CLI with the provided subcommand args and returns its output.

func (*WacliTool) Execute 

func (t *WacliTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*WacliTool) Manifest 

func (t *WacliTool) Manifest() tools.ToolManifest

type WhatsAppMonitorTool 

type WhatsAppMonitorTool struct {
	WacliPath  string
	WebhookURL string   // the KARMAX endpoint the wacli webhook posts to
	Secret     string   // HMAC secret the webhook must be (re)created with
	Protected  []string // operator command chats that must always stay monitored
}

WhatsAppMonitorTool manages which WhatsApp chats KARMAX proactively monitors, by editing the scoped wacli webhook that feeds KARMAX. It is the reliable, single-purpose way for the agent to add/remove/list monitored chats (instead of hand-assembling raw `wacli webhooks` invocations).

func (*WhatsAppMonitorTool) Execute 

func (t *WhatsAppMonitorTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*WhatsAppMonitorTool) Manifest 

func (t *WhatsAppMonitorTool) Manifest() tools.ToolManifest

func (*WhatsAppMonitorTool) Reconcile 

func (t *WhatsAppMonitorTool) Reconcile(ctx context.Context) (bool, int, error)

Reconcile enforces the single-secured-webhook invariant without the agent having to call the tool: if the KARMAX webhook set is fragmented (more than one) or any part is missing the HMAC secret, it collapses them into one secured webhook. Returns (changed, count-of-webhooks-before, error). A no-op when already healthy. Safe to call on a timer / at startup.

type WhatsAppMonitoredTool 

type WhatsAppMonitoredTool struct{}

WhatsAppMonitoredTool reports which chats KARMAX is watching.

func (*WhatsAppMonitoredTool) Execute 

func (t *WhatsAppMonitoredTool) Execute(ctx context.Context, _ map[string]any) (tools.ToolResult, error)

func (*WhatsAppMonitoredTool) Manifest 

func (t *WhatsAppMonitoredTool) Manifest() tools.ToolManifest

type WhatsAppReadTool 

type WhatsAppReadTool struct {
	WacliPath   string       // path to the wacli binary
	DefaultChat string       // chat used when none is specified
	Store       *store.Store // optional: resolves WhatsApp numbers -> saved contact names
}

WhatsAppReadTool reads recent WhatsApp messages via the local wacli binary, giving the agent real-time awareness of the operator's conversations.

func (*WhatsAppReadTool) Execute 

func (t *WhatsAppReadTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*WhatsAppReadTool) Manifest 

func (t *WhatsAppReadTool) Manifest() tools.ToolManifest

type WhatsAppSendMediaTool 

type WhatsAppSendMediaTool struct {
	WacliPath string
}

WhatsAppSendMediaTool sends a local file (image, PDF, spreadsheet, etc.) as a WhatsApp media message via wacli. Pair it with claude_code.call to generate a file (a report, a chart, an exported sheet) and then deliver it.

func (*WhatsAppSendMediaTool) Execute 

func (t *WhatsAppSendMediaTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*WhatsAppSendMediaTool) Manifest 

func (t *WhatsAppSendMediaTool) Manifest() tools.ToolManifest

type WhatsAppViewMediaTool 

type WhatsAppViewMediaTool struct {
	WacliPath string
	Store     *store.Store
	AgentID   string
	Namespace string
}

WhatsAppViewMediaTool downloads a received WhatsApp media message and reads its content — images (described/OCR'd), PDFs, and spreadsheets (extracted) — by delegating the actual understanding to the Claude Code harness, which can view and parse all of them. Incoming media messages arrive with a marker telling the agent the chat + message_id to pass here.

func (*WhatsAppViewMediaTool) Execute 

func (t *WhatsAppViewMediaTool) Execute(ctx context.Context, input map[string]any) (tools.ToolResult, error)

func (*WhatsAppViewMediaTool) Manifest 

func (t *WhatsAppViewMediaTool) Manifest() tools.ToolManifest

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.