@tenphi/akno 0.1.0

package/dist/output.js

@@ -0,0 +1,87 @@
+import { styleText } from 'node:util';
+function wrap(format) {
+    return (text) => styleText(format, text, { stream: process.stdout });
+}
+export const style = {
+    bold: wrap('bold'),
+    dim: wrap('dim'),
+    red: wrap('red'),
+    green: wrap('green'),
+    yellow: wrap('yellow'),
+    blue: wrap('blue'),
+    cyan: wrap('cyan'),
+    grey: wrap('gray'),
+};
+export function heading(text) {
+    process.stdout.write(`\n${style.bold(text)}\n`);
+}
+export function line(text = '') {
+    process.stdout.write(`${text}\n`);
+}
+export function json(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function fail(message) {
+    process.stderr.write(`${styleText('red', 'error', { stream: process.stderr })} ${message}\n`);
+}
+export function warn(message) {
+    process.stderr.write(`${styleText('yellow', 'warning', { stream: process.stderr })} ${message}\n`);
+}
+/** Aligned key/value block. `-` in the value column reads better than empty. */
+export function kv(entries, indent = '  ') {
+    const width = Math.max(...entries.map(([key]) => key.length));
+    for (const [key, value] of entries) {
+        line(`${indent}${style.grey(key.padEnd(width))}  ${value ?? '-'}`);
+    }
+}
+/**
+ * A status is not decoration — `empty` and `unavailable` mean different things
+ * to the caller, and the colour is there so a human scanning output does not have
+ * to read the word to notice which one happened.
+ */
+export function statusLabel(status) {
+    switch (status) {
+        case 'ok':
+            return style.green('ok');
+        case 'empty':
+        case 'degraded':
+            return style.yellow(status);
+        case 'unavailable':
+            return style.red('unavailable');
+        case 'failed':
+            return style.red('failed');
+        default:
+            return status;
+    }
+}
+/** In-place progress on a TTY; one line per phase otherwise, so logs stay readable. */
+export function progressWriter() {
+    let lastPhase = '';
+    const dim = (text) => styleText('gray', text, { stream: process.stderr });
+    return (phase, done, total, detail) => {
+        if (!process.stderr.isTTY) {
+            if (phase !== lastPhase) {
+                lastPhase = phase;
+                process.stderr.write(`${phase}: ${total}\n`);
+            }
+            return;
+        }
+        const label = detail ? ` ${truncate(detail, 46)}` : '';
+        const bar = total > 0 ? `${done}/${total}` : `${done}`;
+        process.stderr.write(`\r\u001b[2K${dim(phase.padEnd(10))} ${bar}${dim(label)}`);
+        if (phase === 'done')
+            process.stderr.write('\r\u001b[2K');
+    };
+}
+export function truncate(text, max) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= max ? collapsed : `${collapsed.slice(0, max - 1)}…`;
+}
+export function ms(value) {
+    if (value < 1)
+        return `${value.toFixed(2)}ms`;
+    if (value < 1000)
+        return `${value.toFixed(0)}ms`;
+    return `${(value / 1000).toFixed(1)}s`;
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"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"}

package/dist/serve/http.d.ts

@@ -0,0 +1,19 @@
+import type { Akno } from '@tenphi/akno-core';
+export interface HttpServer {
+    readonly address: string;
+    close(): Promise<void>;
+}
+/**
+ * For agents in containers or on another host: Akno runs on the host and
+ * the agent reaches it over the network, so the knowledge base and the index never
+ * need to be mounted into a sandbox — which also keeps the single-writer property
+ * that makes WAL concurrency safe.
+ *
+ * Binds loopback unless told otherwise, and says so loudly if not: this door has
+ * no authentication of its own and is meant to sit behind one.
+ */
+export declare function serveHttp(akno: Akno, address: string, options?: {
+    allow?: string[];
+    log?: (message: string) => void;
+}): Promise<HttpServer>;
+//# sourceMappingURL=http.d.ts.map

package/dist/serve/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/serve/http.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAG9C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAClE,OAAO,CAAC,UAAU,CAAC,CAyBrB"}

package/dist/serve/http.js

@@ -0,0 +1,135 @@
+import http from 'node:http';
+import { AknoError, OPS, PROTOCOL_VERSION, isOpName } from '@tenphi/akno-protocol';
+import { AKNO_VERSION } from "../version.js";
+/**
+ * For agents in containers or on another host: Akno runs on the host and
+ * the agent reaches it over the network, so the knowledge base and the index never
+ * need to be mounted into a sandbox — which also keeps the single-writer property
+ * that makes WAL concurrency safe.
+ *
+ * Binds loopback unless told otherwise, and says so loudly if not: this door has
+ * no authentication of its own and is meant to sit behind one.
+ */
+export async function serveHttp(akno, address, options = {}) {
+    const [host, portText] = splitAddress(address);
+    const port = Number(portText);
+    if (!Number.isInteger(port) || port <= 0) {
+        throw new AknoError('invalid', `not a valid host:port — ${address}`);
+    }
+    const server = http.createServer((request, response) => {
+        void route(request, response, akno, options);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    return {
+        address: `${host}:${port}`,
+        async close() {
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+async function route(request, response, akno, options) {
+    const url = new URL(request.url ?? '/', 'http://localhost');
+    if (url.pathname === '/hello') {
+        const hello = {
+            hello: 'akno',
+            protocol: PROTOCOL_VERSION,
+            version: AKNO_VERSION,
+            writable: akno.writable,
+            akno_path: akno.config.aknoPath,
+            ops: options.allow ?? Object.keys(OPS),
+        };
+        send(response, 200, hello);
+        return;
+    }
+    if (url.pathname === '/health') {
+        send(response, 200, { ok: true, writable: akno.writable });
+        return;
+    }
+    const match = /^\/op\/([a-z_]+)$/.exec(url.pathname);
+    if (!match || request.method !== 'POST') {
+        send(response, 404, { ok: false, error: { code: 'not_found', message: 'POST /op/<name>' } });
+        return;
+    }
+    const op = match[1];
+    try {
+        if (!isOpName(op))
+            throw new AknoError('invalid', `unknown op: ${op}`);
+        if (options.allow && !options.allow.includes(op)) {
+            throw new AknoError('forbidden', `${op} is not allowed on this door`);
+        }
+        const input = await readJson(request);
+        // A header rather than a field in the body: `actor` is about the caller, not the op, and putting
+        // it in the JSON would collide the day an op wants a field of that name.
+        const declared = request.headers['x-akno-actor'];
+        const actor = declared === 'user' || declared === 'agent' || declared === 'akno' ? declared : undefined;
+        const started = performance.now();
+        const result = await akno.call(op, input, actor ? { actor } : {});
+        options.log?.(`${op} ${(performance.now() - started).toFixed(1)}ms`);
+        send(response, 200, { ok: true, result });
+    }
+    catch (err) {
+        const error = AknoError.from(err);
+        options.log?.(`${op} ${error.code}: ${error.message}`);
+        send(response, statusFor(error.code), { ok: false, error: error.toJSON() });
+    }
+}
+/** HTTP status codes chosen so a proxy or a dashboard reads them correctly. */
+function statusFor(code) {
+    switch (code) {
+        case 'invalid':
+            return 400;
+        case 'forbidden':
+            return 403;
+        case 'not_found':
+            return 404;
+        case 'read_only':
+        case 'busy':
+            return 409;
+        case 'not_implemented':
+            return 501;
+        case 'unavailable':
+            return 503;
+        default:
+            return 500;
+    }
+}
+function send(response, status, body) {
+    const payload = JSON.stringify(body);
+    response.writeHead(status, {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(payload),
+    });
+    response.end(payload);
+}
+async function readJson(request) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        bytes += chunk.length;
+        // A 4 MB cap: `remember` takes a transcript, not a corpus.
+        if (bytes > 4 * 1024 * 1024)
+            throw new AknoError('invalid', 'request body too large');
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return {};
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new AknoError('invalid', 'request body is not valid JSON');
+    }
+}
+function splitAddress(address) {
+    const index = address.lastIndexOf(':');
+    if (index === -1)
+        return ['127.0.0.1', address];
+    return [address.slice(0, index) || '127.0.0.1', address.slice(index + 1)];
+}
+//# sourceMappingURL=http.js.map

package/dist/serve/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/serve/http.ts"],"names":[],"mappings":"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"}

package/dist/serve/mcp.d.ts

@@ -0,0 +1,21 @@
+import { type OpName } from '@tenphi/akno-protocol';
+import type { OpInput, OpResult } from '@tenphi/akno-protocol';
+/**
+ * The stdio MCP door, for third-party agents that speak it:
+ *
+ *   { "mcpServers": { "memory": { "command": "akno", "args": ["serve", "--mcp"] } } }
+ *
+ * Every tool is generated from the op registry, so an op cannot exist over the
+ * socket and be missing here. Trust is a parameter: `server.mcp_allow` in config
+ * decides which ops this door exposes, and denying `forget` to a sandboxed agent
+ * needs no second code path.
+ */
+export declare function serveMcp(akno: {
+    call<N extends OpName>(op: N, input: OpInput<N>): Promise<OpResult<N>>;
+}, options?: {
+    allow?: string[];
+    log?: (message: string) => void;
+}): Promise<{
+    close(): Promise<void>;
+}>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/serve/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/serve/mcp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmC,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAG/D;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAG5B,IAAI,EAAE;IAAE,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;CAAE,EAChF,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAClE,OAAO,CAAC;IAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAuErC"}

package/dist/serve/mcp.js

@@ -0,0 +1,79 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { AknoError, MCP_SERVER_NAME, OPS } from '@tenphi/akno-protocol';
+import { AKNO_VERSION } from "../version.js";
+/**
+ * The stdio MCP door, for third-party agents that speak it:
+ *
+ *   { "mcpServers": { "memory": { "command": "akno", "args": ["serve", "--mcp"] } } }
+ *
+ * Every tool is generated from the op registry, so an op cannot exist over the
+ * socket and be missing here. Trust is a parameter: `server.mcp_allow` in config
+ * decides which ops this door exposes, and denying `forget` to a sandboxed agent
+ * needs no second code path.
+ */
+export async function serveMcp(
+// Ops, not an `Akno`: this door is equally happy in front of an in-process index or of a
+// socket connection to the service that holds the write handle. Nothing here needs more.
+akno, options = {}) {
+    const server = new McpServer({ name: MCP_SERVER_NAME, version: AKNO_VERSION }, {
+        // Named "memory" and described as memory, deliberately. A model reasons better about a
+        // faculty it has than about a product it has been integrated with, and the brand is not
+        // a fact it can use: what it needs is that recall is where knowledge of this user lives,
+        // and what the status fields mean.
+        instructions: 'This is the user’s long-term memory, stored as a Markdown knowledge base. Use `answer` for a direct ' +
+            'factual response grounded entirely in memory, or `recall` when evidence must be inspected, compared, ' +
+            'or quoted. Do not call both by default: answer already performs bounded recall and returns compact ' +
+            'related identities. Recall’s typed page and document results carry source addresses, so a claim you ' +
+            'take from them can be cited and a claim you cannot find in them should not be made. Read `status` on ' +
+            'every result: "empty" means the knowledge base ' +
+            'genuinely has nothing and you may say so; "degraded" means part of the search stack was ' +
+            'missing, so absence is not proven; "unavailable" means the index could not be read. In ' +
+            'question mode, `coverage` tells you which parts of the question the results actually cover — ' +
+            'do not answer the parts marked false. Values returned under `superseded` are historical, not ' +
+            'current.',
+    });
+    const allowed = (options.allow ?? Object.keys(OPS));
+    for (const name of allowed) {
+        const definition = OPS[name];
+        if (!definition)
+            continue;
+        server.registerTool(name, {
+            title: name,
+            description: definition.implemented
+                ? definition.description
+                : `${definition.description} NOT AVAILABLE in this build — calling it returns not_implemented.`,
+            inputSchema: definition.input,
+        }, async (input) => {
+            try {
+                const started = performance.now();
+                const result = await akno.call(name, input);
+                options.log?.(`mcp ${name} ${(performance.now() - started).toFixed(1)}ms`);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            catch (err) {
+                const error = AknoError.from(err);
+                options.log?.(`mcp ${name} ${error.code}: ${error.message}`);
+                // An error returned as content rather than thrown lets the agent read
+                // the code and react — the whole point of `degraded` vs `empty`.
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ status: 'error', ...error.toJSON() }, null, 2),
+                        },
+                    ],
+                };
+            }
+        });
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    return {
+        async close() {
+            await server.close();
+        },
+    };
+}
+//# sourceMappingURL=mcp.js.map

package/dist/serve/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/serve/mcp.ts"],"names":[],"mappings":"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"}

package/dist/serve/socket.d.ts

@@ -0,0 +1,15 @@
+import { type Akno } from '@tenphi/akno-core';
+export interface SocketServer {
+    readonly path: string;
+    close(): Promise<void>;
+}
+/**
+ * The default door: no port, filesystem permissions are the auth, and it is
+ * the fastest. Newline-delimited JSON over a unix socket, framed by the protocol
+ * package so this file and the client cannot disagree about the wire.
+ */
+export declare function serveSocket(akno: Akno, socketPath: string, options?: {
+    allow?: string[];
+    log?: (message: string) => void;
+}): Promise<SocketServer>;
+//# sourceMappingURL=socket.d.ts.map

package/dist/serve/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/serve/socket.ts"],"names":[],"mappings":"AAgBA,OAAO,EAGL,KAAK,IAAI,EAIV,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAClE,OAAO,CAAC,YAAY,CAAC,CA4EvB"}