@augmentd-labs/canvas-edge 0.0.0-stage → 0.4.1

package/NOTICE

@@ -0,0 +1,112 @@
+Canvas
+Copyright (C) 2023-2026 Jozef Melich
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License along
+with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Contact:
+    lic@augmentd.eu       licensing
+    contrib@augmentd.eu   contributions
+    security@augmentd.eu  security
+
+
+NETWORK USE
+-----------
+
+Section 13 of the AGPL applies to this software. If you run a modified version
+and let users interact with it over a network, those users must be able to
+obtain the corresponding source of your modified version.
+
+This server implements its side of that obligation. Every HTTP response carries
+an `X-Source-Code` header, and `GET /rest/v2/ping` (no authentication required)
+reports the running version, revision and source URL:
+
+    curl -sI https://your-host/ | grep -i x-source-code
+    curl -s  https://your-host/rest/v2/ping
+
+If you deploy a modified version, repoint these at the repository that publishes
+your changes. Set `CANVAS_SOURCE_URL`, and set `CANVAS_SOURCE_COMMIT` where the
+build has no git metadata, as in the container image. Removing the notice
+instead of repointing it does not satisfy the licence.
+
+
+COPYRIGHT AND COMMERCIAL LICENSING
+----------------------------------
+
+Copyright in this codebase is held by Jozef Melich. Augmentd s.r.o. holds an
+exclusive licence to it, including the right to grant sublicences, and is the
+entity authorised to issue commercial licences for Canvas.
+
+The AGPL is not the only option for the components marked [dual] below. If its
+terms do not work for you, most often because you want to build a commercial or
+hosted product on Canvas without publishing your own changes, a separate
+commercial licence is available for those components, and no AGPL obligation
+applies to it. See COMMERCIAL.md.
+
+The Canvas clients marked [AGPL] are available under the AGPL-3.0-or-later and
+under no other terms. No commercial licence is offered for them to anyone,
+including holders of a commercial licence to the server runtime. The clients
+stay free software in all cases.
+
+Licensing enquiries: lic@augmentd.eu
+
+    Augmentd s.r.o.
+    DUETT Business Center
+    Námestie Osloboditeľov 3/A
+    040 01 Košice, Slovakia
+    Company ID: 45331936
+    VAT ID: SK2022968717
+    https://augmentd.eu
+
+
+COMPONENTS
+----------
+
+Canvas is assembled from several repositories. They are not all licensed the
+same way. Every component is available under the AGPL-3.0-or-later; only those
+marked [dual] are also available under a commercial licence. Components in
+separate repositories each carry their own LICENSE and NOTICE.
+
+The server runtime and the services behind it, together the engine:
+
+    [dual]  canvas-server   this repository, server runtime, transports, core
+              src/services/messaging  notification and chat channels
+              src/services/voice      speech-to-text and text-to-speech
+              src/core/agent          agent runtime
+    [dual]  canvas-synapsd  (dependency) context indexing engine
+    [dual]  canvas-stored   (dependency) blob storage
+    [dual]  canvas-inferd   (dependency) inference service
+    [dual]  canvas-agentd   (repository) agent runtime service, consolidating
+                            the former canvas-neurald
+    [dual]  canvas-common/packages/* (repository)   shared libraries: protocol, schemas,
+                            api-client
+
+The client applications, AGPL-only for everyone:
+
+    [AGPL]  canvas-cli             (repository) command-line client and shell
+    [AGPL]  canvas-web             (repository) web UI, served by this server
+    [AGPL]  canvas-desktop         (repository) desktop app
+    [AGPL]  canvas-browser-extension (repository) Chrome and Firefox extensions
+    [AGPL]  canvas-fuse            (repository) FUSE filesystem client
+
+A commercial licence to a [dual] component grants no rights over an [AGPL] one.
+If you hold a commercial licence to the server runtime and you modify and convey
+the CLI, the AGPL applies to that CLI in full. The same holds for the web UI:
+it is AGPL-only, and serving a modified web UI to users over a network obliges
+you to offer them its corresponding source, whatever engine licence you hold.
+
+
+THIRD-PARTY CODE
+----------------
+
+Third-party dependencies keep their own licences. See the dependency manifests
+and node_modules for their terms. This notice covers Canvas code only.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @augmentd-labs/canvas-edge
 
-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.
+The device-side Canvas runtime. One Node process, two jobs:
+
+- **mirror** — keep real folders in sync with hub workspaces (canvas-stored's
+  `Mirror` engine, state under `<folder>/.workspace/` or an external state dir). Configured by the CLI's
+  `~/.canvas/config/mirrors.json` (`canvas remote mirror init`), driven over a local
+  control socket (`~/.canvas/run/edge.sock`, a localhost port on Windows).
+- **tunnel** — `EdgeClient` dials out to a canvas-server, announces what this
+  runtime hosts and replays proxied requests into a local fastify app, so a
+  remote workspace or agent behaves as if it were server-local. The hub side
+  (`EdgeRegistry`) lives in canvas-server.
+
+No canvas-server imports: the same package backs `ws`, canvas-agentd and the
+desktop sidecar. This is the seed of the generic standalone runtime
+(`mirror | workspace | agent` units behind one lifecycle).
+
+```
+canvas-edge --foreground        # run attached (pm2 / systemd); logs to stdout
+canvas-edge                     # detached, logs to ~/.canvas/var/log/canvas-edge.log
+```
+
+## Install
+
+Published to npm as `@augmentd-labs/canvas-edge` (canvas-common's
+release.yml, on a version bump). The CLI fetches it into its own prefix:
+
+```
+canvas remote mirror edge install      # → ~/.canvas/edge/node_modules/@augmentd-labs/canvas-edge
+canvas remote mirror edge update       # latest from npm + restart the daemon
+```
+
+(`npm install --ignore-scripts @augmentd-labs/canvas-edge` in any project does
+the same; avoid `npm -g` — global installs of packages with bundled deps came
+out incomplete on npm 11.) `canvas remote mirror init` offers the
+install when the binary is missing. The
+artifact bundles its workspace/git dependencies (canvas-protocol,
+canvas-stored) and keeps only registry dependencies external — see
+`scripts/pack-dist.mjs`.
+
+## fuse units (on-demand mounts, e.g. a GPU workstation)
+
+A mirrors.json entry with `client: 'fuse', managed: 'edge'` is a **fuse unit**:
+the daemon spawns `canvas-fuse mount -w <ws> <root> --remote <id> --mirror …`
+attached, restarts it with backoff when it dies, reads `canvas-fuse status
+--json` for its state and unmounts it on stop — one process per workspace
+under one root (`<root>/<folder>`), as many units as workspaces. canvas-fuse
+stays a plain executable (`CANVAS_FUSE_BIN`, `~/.cargo/bin`, PATH); its
+on-demand namespace, content cache, pins and LRU are its own. `canvas remote
+mirror add <ws> --edge` (or `… supervisor <ws> edge`) configures one.
+
+## Container (NAS, servers)
+
+`runtimes/edge/Dockerfile` installs the npm package into an
+unprivileged image; one container mirrors one workspace, configured by
+environment (no CLI needed on the host):
+
+```
+docker build -t canvas-edge -f runtimes/edge/Dockerfile .
+docker run -d --name canvas-edge-augmentd --restart unless-stopped \
+  -e CANVAS_HUB_URL=https://canvas.example.org -e CANVAS_HUB_TOKEN=canvas-… \
+  -e CANVAS_WORKSPACE=augmentd -e CANVAS_DIRECTION=pull -e CANVAS_DEVICE_ID=nas-synology \
+  -v /volume1/work/Augmentd:/data -v canvas-edge-config:/config -v canvas-edge-state:/state \
+  canvas-edge
+```
+
+`docker/docker-compose.example.yml` is the same as a compose project (what
+Synology Container Manager takes). `canvas remote mirror docker <workspace>`
+prints one filled in from a remote you are logged in to. State (ledger,
+queue, cache, trash, conflicts) lives under `/state/<mirror id>`
+(`CANVAS_EDGE_STATE_ROOT`), so the mirrored share holds user files only; a
+non-container mirror gets the same with `--state-dir` (`stateDir` in
+mirrors.json). `CANVAS_DIRECTION=pull` makes the container a backup target
+(hub is the only writer), `bi` while seeding from existing files.
+
+Protocol: canvas-server `docs/canvas-edge-protocol.md` (tunnel) and
+`docs/sync-protocol.md` (file plane).

package/bin/canvas-edge

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/daemon.js').then((m) => m.main()).catch((err) => { console.error(err); process.exit(1); });

package/bin/healthcheck.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Container health: the control socket answers /status. Exit 0 when it does.
+import http from 'node:http';
+import { EDGE_PATHS } from '../src/env.js';
+
+const opts = EDGE_PATHS.socket ? { socketPath: EDGE_PATHS.socket, path: '/status' } : { host: '127.0.0.1', port: EDGE_PATHS.port, path: '/status' };
+const req = http.get(opts, (res) => { process.exit(res.statusCode === 200 ? 0 : 1); });
+req.on('error', () => process.exit(1));
+req.setTimeout(5000, () => { req.destroy(); process.exit(1); });