Safe Haskell	None
Language	GHC2024

Free.Agent.Host

Description

One-shot host algebra over circuits-agent seats.

A Host is a named effectful seat that receives arguments drawn from the body of an incoming post and produces lines of output. Live CLI agents are Cli recipes from Cli — session management (scrape, resume, stale fallback) lives there, not here.

Synopsis

data BodyMode
- = BodyWords
- | BodyLines
- | BodyWhole
data Host = Host {
- hostName :: Text
- hostBodyMode :: BodyMode
- hostRun :: [Text] -> IO [Text]
}
data BareConfig = BareConfig {
- agentName :: Text
- baseUrl :: Text
- model :: Text
- key :: Text
}
mkHost :: Text -> ([Text] -> IO [Text]) -> Host
hostShard :: Host -> AgentShard [Post Text] [Post Text]
processHost :: Text -> FilePath -> [String] -> Host
cliHost :: Text -> Cli -> Host
hermesHost :: Text -> Text -> Maybe Text -> Maybe Text -> Bool -> FilePath -> Maybe (IORef Int, FilePath) -> Host
hermesHostBatch :: Text -> Text -> Maybe Text -> Maybe Text -> Bool -> FilePath -> Maybe (IORef Int, FilePath) -> Host
hermesCli :: Maybe Text -> Maybe Text -> Bool -> FilePath -> Maybe (IORef Int, FilePath) -> Cli
kimiHost :: Text -> Maybe Text -> Maybe Text -> FilePath -> Maybe (IORef Int, FilePath) -> Host
bareHost :: BareConfig -> Text -> Host
defaultBareConfig :: BareConfig

Documentation

data BodyMode Source #

How to turn a post body into arguments for hostRun.

Constructors

BodyWords	Split on whitespace (default).
BodyLines	Split on newlines.
BodyWhole	Pass the whole body as a single argument.

Instances

Instances details

Eq BodyMode Source #
Instance details Defined in Free.Agent.Host Methods (==) :: BodyMode -> BodyMode -> Bool # (/=) :: BodyMode -> BodyMode -> Bool #
Show BodyMode Source #
Instance details Defined in Free.Agent.Host Methods showsPrec :: Int -> BodyMode -> ShowS # show :: BodyMode -> String # showList :: [BodyMode] -> ShowS #

data Host Source #

A one-shot host seat.

The host receives arguments derived from the body of an incoming post and produces output lines. The caller decides how to turn those lines back into posts; hostShard uses the default mapping (reply to sender).

Constructors

Host
Fields hostName :: Text Name used as the `from` field of reply posts. hostBodyMode :: BodyMode How to split the incoming post body before calling `hostRun`. hostRun :: [Text] -> IO [Text] Run the host on the prepared arguments.

data BareConfig Source #

Connection configuration for a direct API host.

Constructors

BareConfig
Fields agentName :: Text Identity / from-field for reply posts. baseUrl :: Text API base URL, e.g. "https://api.deepseek.com/v1". model :: Text Model name, e.g. "deepseek-v4-pro". key :: Text API key.

Instances

Instances details

Eq BareConfig Source #
Instance details Defined in Free.Agent.Host Methods (==) :: BareConfig -> BareConfig -> Bool # (/=) :: BareConfig -> BareConfig -> Bool #
Show BareConfig Source #
Instance details Defined in Free.Agent.Host Methods showsPrec :: Int -> BareConfig -> ShowS # show :: BareConfig -> String # showList :: [BareConfig] -> ShowS #

mkHost :: Text -> ([Text] -> IO [Text]) -> Host Source #

Smart constructor with the default BodyWords mode.

hostShard :: Host -> AgentShard [Post Text] [Post Text] Source #

Turn a host into a stateful shard that consumes every committed post.

The shard remembers the committed posts in its state. On emit it runs the host on each post's body (prepared by hostBodyMode), in order, and emits one reply post per output line per input post. Each reply is addressed back to the sender of its input post.

Note: a generic host has no access to stamped log ids, so emitted replies carry no thread edge. Callers that need provenance should thread by id outside the host.

processHost Source #

Arguments

:: Text	Host name.
-> FilePath	Command to run.
-> [String]	Fixed command arguments.
-> Host

A host backed by an external process.

The command receives the fixed args followed by the prepared post body (one argument when BodyWhole, whitespace-split words by default). Output lines become reply posts. Uses readProcess.

cliHost Source #

Arguments

:: Text	Host name (used as the `from` field of reply posts).
-> Cli	Invocation recipe.
-> Host

A host backed by a live CLI agent recipe (Cli).

Each prepared body becomes one cliQuery; session scraperesumestale fallback happens inside the recipe. One reply text per body (multi-line bodies and replies are preserved).

hermesHost Source #

Arguments

:: Text	Host name (used as the `from` field of reply posts).
-> Text	System prompt text prepended to every body.
-> Maybe Text	Model name passed to `hermes -m`, if any.
-> Maybe Text	Provider passed to `hermes --provider`, if any.
-> Bool	Pass `--yolo -Q` to hermes.
-> FilePath	Session file for cross-call context.
-> Maybe (IORef Int, FilePath)	Optional transcript sink.
-> Host

Hermes host on the shared Cli seat.

Runs hermes chat -q per body, prepending the supplied system prompt to the body in the query. The optional model and provider override the CLI defaults; Nothing keeps the hermes CLI default. yolo controls whether --yolo -Q is passed to hermes. Sessions persist across calls via sessionFile; a stale session falls back to fresh.

When mTranscript is Just, one JSONL transcript record is appended to the given file per invocation. The caller writes the post id to the IORef before each call; see cliQuery for details.

The caller is responsible for building the system prompt; this function knows nothing about design documents, protocol cards, or magic wording.

hermesHostBatch Source #

Arguments

:: Text	Host name (used as the `from` field of reply posts).
-> Text	System prompt text prepended to every body.
-> Maybe Text	Model name passed to `hermes -m`, if any.
-> Maybe Text	Provider passed to `hermes --provider`, if any.
-> Bool	Pass `--yolo -Q` to hermes.
-> FilePath	Session file for cross-call context.
-> Maybe (IORef Int, FilePath)	Optional transcript sink.
-> Host

Batch variant of hermesHost. Joins all post bodies into a single user message and makes one hermes chat -q call, returning one reply. Use when multiple posts may arrive in a single wake cycle and the agent should see them as a combined conversation turn.

hermesCli :: Maybe Text -> Maybe Text -> Bool -> FilePath -> Maybe (IORef Int, FilePath) -> Cli Source #

Shared CLI recipe for hermes backends. When cliTranscript is Just, one JSONL record is appended per invocation.

kimiHost Source #

Arguments

:: Text	Host name (used as the `from` field of reply posts).
-> Maybe Text	Model name passed to `kimi -m`, if any.
-> Maybe Text	Provider passed to `kimi --provider`, if any.
-> FilePath	Session file for cross-call context.
-> Maybe (IORef Int, FilePath)	Optional transcript sink.
-> Host

Kimi host on the shared Cli seat.

Runs kimi -p per body (see kimiCli), with optional -m model, --provider provider, and session resume via sessionFile. A stale session falls back to fresh.

When mTranscript is Just, one JSONL transcript record is appended to the given file per invocation. The caller writes the post id to the IORef before each call; see cliQuery for details.

bareHost Source #

Arguments

:: BareConfig	Connection configuration.
-> Text	System prompt.
-> Host

A host backed by a direct OpenAI-compatible chat completions API call.

The caller supplies the system prompt; the post body becomes the user message. There is no tooling, memory, or context-file injection.

defaultBareConfig :: BareConfig Source #

Sensible defaults for an OpenAI-compatible DeepSeek host.