Connectors

A connector is a program you declare in kusaw.yaml that the factory talks to as a client: an MCP server (a local command or a hosted URL) or a small command program. Connectors bring outside work and context into the factory. They are off until you declare one, and you can declare up to 20.

How a connector is wiredCopy Anchor Link

connectors:
  demo-tracker:
    mcp:
      command: ["kusaw", "connector", "demo-files", "--dir", "items"]
    intake:
      tool: list_items
      mode: hold        # new items wait for you; queue starts them right away
    agent_tools: [get_item]

• mcp is the transport: command for a local stdio server, or url (plus headers) for a hosted one. command at the top level of the entry is a command connector instead of MCP.
• env (command connectors only) sets environment variables for the connector's own process. Each entry is { value: "..." } or { secret: true }; store a secret with kusaw config set --secret connectors.<name>.env.<NAME>. Secret values are redacted from what the connector returns. An MCP server uses mcp.env instead.
• intake polls a tool while kusaw serve runs. With mode: hold, new items wait in kusaw connector items until you kusaw connector accept or kusaw connector ignore them.
• context writes named context files into each attempt from tool calls.
• agent_tools lists the read tools agents may call during a step, through the per-attempt factory-connectors proxy.
• write_back maps tools that change the outside system. Their calls are effects held at the run-end gate until you apply them with kusaw effects apply <run>.

Every key is in the kusaw.yaml reference.

SafetyCopy Anchor Link

Items and tool results are fenced as untrusted connector:<name> data before a step sees them. Secrets go in with kusaw config set --secret and reach only that connector's process or its HTTP requests; they never reach a step, an agent session, a log, or an event. A hosted connector gets an outside-service warning from kusaw validate. See What stays local and what doesn't.

CommandsCopy Anchor Link

• kusaw connector — list, check (list mapped tools and pin their definitions), call, items, accept, ignore, changes, and sync.
• kusaw docs show — print the document-store context a step would get.
• kusaw effects — list a run's effects, and apply or reject held ones.
• kusaw logs fingerprints — log-store error groups, with ignore and link.