@hivemagnus/ardent 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,275 @@
-# Temporary Holding Version
+# Ardent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ardent is a headless TypeScript agent runtime. One process serves one
+**profile**: a directory with a YAML config, a persona (`SOUL.md`,
+`IDENTITY.md`), skills, and private SQLite state. Ardent runs model turns
+against an OpenAI-compatible chat server (llama.cpp, vLLM, ...) or the Codex
+App Server, calls typed tools, and keeps a durable journal of every task.
+
+What you get:
+
+- **Durable tasks** with idempotency keys, cancellation, deadlines, and a
+  per-task event journal in SQLite. Interrupted work is marked `unknown`,
+  never silently replayed.
+- **Management API** (Hono, bearer-token protected) for tasks, sessions,
+  config, identity, skills, peers, channels, and live event streams. The
+  OpenAPI document is served at `/openapi.json` and pinned in
+  [`openapi/ardent.json`](openapi/ardent.json).
+- **A2A protocol 1.0** server and client over JSON-RPC, HTTP+JSON, and gRPC,
+  with authenticated peers, push notifications, and bounded "team missions"
+  that scope which tools a peer may reach.
+- **Scheduled jobs** (cron with IANA timezones, or fixed intervals) with
+  exactly-once window receipts.
+- **Skills**: Markdown working methods the model can read on demand.
+- **Context compaction** for long sessions, driven by a model policy file.
+- **Optional integrations**: news research (SearXNG + Firecrawl), HiveMem
+  long-term memory, Telegram and Mattermost chat channels, read-only Magnus
+  Control tools, and Hermes Agent team-card compatibility. Each one is off
+  until you configure it.
+- **Plugins**: add tools, API routes, CLI commands, and job handlers from a
+  separate npm package.
+
+## Install
+
+Ardent needs Node.js 24.22.1+ or 26.13.0+ (`better-sqlite3` is a native
+dependency).
+
+```bash
+npm i -g @hivemagnus/ardent
+ardent init --non-interactive            # creates ~/.ardent/profiles/assistant
+ardent doctor                            # lists unresolved configuration
+```
+
+`init` copies the bundled `assistant` template, sets the profile timezone to
+the host's zone, and writes a random management token to the profile's
+`.env`. Use `--profile NAME` (or `--profile-path /abs/dir`) to create and
+select other profiles, and `--api-port N` to choose the management port.
+`ARDENT_HOME` overrides the `~/.ardent` root.
+
+Point the profile at a model, then talk to it:
+
+```bash
+cat >> ~/.ardent/profiles/assistant/.env <<'EOF'
+ARDENT_LLAMA_BASE_URL=http://127.0.0.1:8080/
+ARDENT_LLAMA_MODEL=your-model-name
+EOF
+ardent chat                              # interactive session
+ardent run --prompt "Summarize RFC 9110 in three bullets"
+ardent gateway run                       # management API, A2A, channels, jobs
+```
+
+`ardent help` lists every command.
+
+## Configuration
+
+`config.yaml` (schema 1) is validated strictly; unknown keys are rejected. A
+string of the form `${NAME}` is resolved from the environment (the profile
+`.env` is loaded automatically). Secrets are never written to the config,
+only the *names* of the environment variables that hold them.
+
+| Key | Default | Notes |
+|---|---|---|
+| `profile`, `name` | required | Profile ID and display name. |
+| `product` | `Ardent` | Shown in the profile summary. |
+| `timezone` | host zone, else `UTC` | IANA zone used for dates shown to the model. Job schedules carry their own zone. |
+| `identity.soul_file`, `identity.identity_file` | `SOUL.md`, `IDENTITY.md` | Persona files in the profile. |
+| `execution` | required | `backend: llamacpp \| codex`, step, tool-call, parallelism, and deadline limits. |
+| `providers.llamacpp` | required | `base_url`, `model`, `api_key_env`, `request_timeout_seconds`, optional `context_window_tokens`, `max_output_tokens`, `reasoning_effort`. |
+| `providers.codex` | required | `command`, `model`, `auth_mode: chatgpt \| api_key` (default `chatgpt`); `approval_policy: never` and `sandbox: read-only` are fixed. |
+| `memory` | `{ provider: none }` | See [HiveMem](#hivemem-memory). |
+| `research` | disabled | `enabled`, `searxng_url`, `firecrawl_url`, `firecrawl_token_env`. Enables the `news_search`, `news_article`, `news_collect`, and `news_capabilities` tools. |
+| `skills` | `directories: [skills]`, `enabled: []` | Only enabled skills are shown to the model. |
+| `a2a` | disabled | See [A2A](#a2a). |
+| `channels.telegram`, `channels.mattermost` | disabled | See [Chat channels](#chat-channels). |
+| `integrations.magnus_control` | disabled | See [Magnus Control tools](#magnus-control-tools). |
+| `plugins` | `[]` | See [Plugins](#plugins). |
+| `api` | `127.0.0.1:9910`, `ARDENT_API_TOKEN` | Management listener and the env var holding its bearer token. A non-loopback host is refused; put a TLS proxy in front instead. |
+
+`ardent config schema` prints the full JSON Schema, and `ardent config
+validate` checks a profile without starting it.
+
+### HiveMem memory
+
+Memory is off by default. To use a HiveMem server:
+
+```yaml
+memory:
+  provider: hivemem
+  base_url: ${HIVEMEM_API_URL}
+  token_env: HIVEMEM_TOKEN
+  agent_id: assistant
+  workspace_id: ${HIVEMEM_WORKSPACE}
+  default_scope: private
+```
+
+Direct conversations then get `hivemem_status`, `hivemem_search`,
+`hivemem_browse`, and explicit write tools. Peers never read private memory; a
+validated team mission may grant read access to one shared `project:<id>`
+scope.
+
+### Chat channels
+
+```yaml
+channels:
+  telegram:
+    enabled: true
+    token_env: TELEGRAM_BOT_TOKEN
+    allowed_user_ids: [123456789]     # only these users are answered
+  mattermost:
+    enabled: true
+    base_url: ${MATTERMOST_URL}       # e.g. https://chat.example.com
+    token_env: MATTERMOST_TOKEN
+    allowed_user_ids: [user-id]
+    require_mention: true
+    reply_mode: thread                # thread | flat
+```
+
+Telegram uses long polling; Mattermost uses its v4 REST and WebSocket APIs.
+Both support `/help`, `/new`, `/status`, `/jobs`, `/model`, `/stop`, `/tasks`,
+and `/sources`. Each inbound message and outbound reply is journaled, so a
+restart never sends the same reply twice.
+
+### A2A
+
+```yaml
+a2a:
+  enabled: true
+  bindings: [jsonrpc, http-json, grpc]
+  public_url: ${ARDENT_A2A_PUBLIC_URL}   # advertised origin, e.g. https://agent.example.com:9900
+  listen_host: 127.0.0.1
+  listen_port: 9900                      # gRPC listens on listen_port + 1
+  peers_file: peers.yaml
+  skill: { id: research, name: Research, description: Sourced answers, tags: [research] }
+  hermes_compat: false
+```
+
+Peers are listed in `peers.yaml` with the environment variables holding their
+inbound and outbound bearer tokens. An ordinary peer task can reach only the
+public news tools. A peer that sends a validated team mission envelope gets
+the tools its `resources` allow (`public:news`, `magnus:fleet`,
+`magnus:node:<id>`, or `tool:<name>` for any registered tool) and must return
+a structured, evidence-checked team result.
+
+`hermes_compat: true` additionally serves the authenticated
+`/.well-known/hermes-team-card.json` discovery document and accepts Hermes
+Agent's slash-style JSON-RPC method aliases (`message/send`, `tasks/get`, ...).
+
+`ardent a2a discover <peer>` and `ardent a2a call <peer> --prompt TEXT` talk
+to configured peers from the command line.
+
+### Magnus Control tools
+
+Read-only fleet tools for a [Magnus](https://github.com/ChefTaco/magnus)
+Control API (fleet inventory, readiness, node health, dependency impact,
+anomalies, command status, and more). Enable them with
+`integrations.magnus_control.enabled: true` or `ARDENT_MAGNUS_CONTROL_TOOLS=true`.
+The base URL comes only from `integrations.magnus_control.base_url` (default
+`${ARDENT_MAGNUS_API_URL}`) and the read token from the env var named by
+`token_env` (default `ARDENT_MAGNUS_READ_TOKEN`). Bearer tokens are sent only
+over HTTPS or to loopback.
+
+### Scheduled jobs
+
+Put job definitions in `jobs/active.json` inside the profile:
+
+```json
+{
+  "schema_version": 1, "profile": "assistant", "revision": 1,
+  "jobs": [{
+    "id": "morning-news", "owner": "ardent", "enabled": true, "handler": "news.collect",
+    "schedule": { "cron": "30 6 * * *", "timezone": "Europe/Berlin", "missed_window": "skip", "catch_up_minutes": 0 },
+    "input": { "query": "open source AI agents", "max_articles": 3 },
+    "delivery": { "kind": "none" },
+    "policy": { "max_attempts": 2, "retry_backoff_seconds": 300 }
+  }]
+}
+```
+
+`ardent jobs definitions validate --source /abs/path.json` checks a file
+before you install it; `ardent jobs definitions status` and
+`GET /api/v1/jobs/definitions/status` report the installed revision and recent
+windows. The built-in handler is `news.collect` (requires `research`); plugins
+add more.
+
+### Model policy
+
+An optional, owner-only `$ARDENT_HOME/model-policy/active.json` selects the
+Codex model and reasoning effort and configures context compaction for all
+profiles under that home. [`model-policy.default.json`](model-policy.default.json)
+is a starting point; compaction is disabled until you enable it.
+
+## Plugins
+
+A plugin is an ES module whose default export (or named `plugin` export) is an
+`ArdentPlugin` object, or an array of them:
+
+```ts
+import { definePlugin } from '@hivemagnus/ardent';
+import { z } from 'zod';
+
+export default definePlugin({
+  name: 'weather',
+  registerTools(ctx) {
+    ctx.tools.register(ctx.defineTool({
+      name: 'weather_now', description: 'Current weather for a city.',
+      input: z.object({ city: z.string().min(1) }).strict(),
+      output: z.object({ summary: z.string() }),
+      effect: 'read', contexts: ['direct'], timeoutMs: 10_000,
+      handler: async ({ city }, signal) => ({ summary: await lookUp(city, signal) }),
+    }));
+  },
+  routes(app, ctx) {                       // served under /api/v1/plugins/weather/
+    app.get('/health', c => c.json({ ok: true, profile: ctx.config.profile }));
+  },
+  cliCommands: {                           // ardent weather-check
+    'weather-check': { description: 'Probe the provider', run: async ({ print }) => print({ ok: true }) },
+  },
+  jobHandlers: ctx => ({ /* 'weather.daily': JobHandler */ }),
+  jobOwnership: ctx => async (job, now) => { /* throw to refuse a job window */ },
+  peerTool: (tool, task, envelope) => false, // allow a peer to call one of your tools
+});
+```
+
+Load it from config, as an npm package name (resolved from the profile
+directory first, then from Ardent's own install), an absolute path, or a
+`file://` URL:
+
+```yaml
+plugins: ['@example/ardent-weather', /opt/ardent/plugins/local.mjs]
+```
+
+Embedders that build the runtime themselves can call `registerPlugin()` before
+loading plugins. Plugin tools join the profile's shared tool registry; a tool's
+`contexts` decides whether direct, peer, or scheduled tasks may call it, and a
+peer still needs an explicit mission grant (`tool:<name>`) or `peerTool`.
+Plugin routes sit behind the same bearer-token check as the rest of the
+management API.
+
+## Security model
+
+- The model never gets a shell, deployment, or credential tool from Ardent
+  itself. Retrieved text, memories, and peer messages are treated as data.
+- Every tool declares its effect (`read`, `artifact-write`, `memory-write`,
+  `external-write`). A cancelled task whose tool call may have had an effect
+  is marked `unknown`, not `cancelled`, and is never retried automatically.
+- Profile state, `.env`, and config are created owner-only (`0600`/`0700`).
+- News URLs are restricted to public HTTP(S) addresses; private and loopback
+  ranges are refused.
+
+## Development
+
+```bash
+npm --workspace @hivemagnus/ardent run typecheck
+npm --workspace @hivemagnus/ardent run lint
+npm --workspace @hivemagnus/ardent test
+npm --workspace @hivemagnus/ardent run build
+npm --workspace @hivemagnus/ardent run openapi:check
+node packages/ardent/scripts/check-package.mjs   # packs, installs, and smoke-tests the tarball
+```
+
+See [AGENTS.md](AGENTS.md) for contributor guidance.
+
+## License
+
+Apache-2.0. The vendored A2A protocol definition in `protocol/` carries its own
+license, [`protocol/LICENSE-A2A.txt`](protocol/LICENSE-A2A.txt).

package/dist/a2a-client.d.ts

@@ -0,0 +1,35 @@
+import { type AgentCard, type ListTasksResponse, type SendMessageResult, type StreamResponse, type Task } from '@a2a-js/sdk';
+import { type Client } from '@a2a-js/sdk/client';
+import type { ArdentConfig } from './config.js';
+import type { A2APushInbox } from './a2a-push-inbox.js';
+export declare function fetchHermesTeamCard(card: AgentCard, authorization: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
+export declare class ArdentA2AClient {
+    readonly profileDir: string;
+    readonly config: ArdentConfig;
+    readonly env: NodeJS.ProcessEnv;
+    readonly pushInbox?: A2APushInbox | undefined;
+    readonly preferredTransports: string[];
+    constructor(profileDir: string, config: ArdentConfig, env?: NodeJS.ProcessEnv, pushInbox?: A2APushInbox | undefined, preferredTransports?: string[]);
+    open(peerId: string): Promise<{
+        card: AgentCard;
+        client: Client;
+        authorization: string;
+    }>;
+    teamControl(peerId: string, control: {
+        version: '1.0';
+        action: string;
+        key: string;
+        payload: object;
+    }): Promise<Record<string, unknown>>;
+    send(peerId: string, prompt: string, signal?: AbortSignal, contextId?: string, taskId?: string): Promise<SendMessageResult>;
+    getTask(peerId: string, id: string, historyLength?: number): Promise<Task>;
+    listTasks(peerId: string, pageSize?: number, pageToken?: string, contextId?: string): Promise<ListTasksResponse>;
+    cancelTask(peerId: string, id: string): Promise<Task>;
+    extendedCard(peerId: string): Promise<AgentCard>;
+    subscribe(peerId: string, id: string, signal?: AbortSignal): AsyncGenerator<StreamResponse>;
+    sendStreaming(peerId: string, prompt: string, signal?: AbortSignal): AsyncGenerator<StreamResponse>;
+    sendWithReceipt(peerId: string, prompt: string, signal?: AbortSignal, contextId?: string, taskId?: string): Promise<{
+        result: SendMessageResult;
+        outboundId?: string;
+    }>;
+}