gws-axi 0.12.0 → 0.13.0

package/README.md

@@ -37,7 +37,7 @@ I want to authenticate the following Google accounts:
   - personal@gmail.com
 ```
 
-The explicit `gws-axi auth setup` in the prompt matters: this is your very first session, so the agent doesn't yet have any ambient context about `gws-axi`. Naming the first command gets the agent into the structured flow, where the CLI's output takes over. Every subsequent session auto-loads a compact `gws-axi` status line via a session-start hook (installed on first invocation) — so after this one, you can skip the command and just say "use gws-axi to ..." and the agent knows.
+The explicit `gws-axi auth setup` in the prompt matters: this is your very first session, so the agent doesn't yet have any ambient context about `gws-axi`. Naming the first command gets the agent into the structured flow, where the CLI's output takes over. Once you install the SessionStart hook (see [step 4](#4-make-gws-axi-your-agents-default-for-google-workspace)), every subsequent session auto-loads a compact `gws-axi` status line — so after that, you can skip the command and just say "use gws-axi to ..." and the agent knows.
 
 Expect ~10 minutes end-to-end for a fresh Google Cloud project; ~3 minutes if you already have one you want to reuse.
 
@@ -54,7 +54,15 @@ gws-axi calendar events                  # upcoming 7 days on your primary calen
 
 ### 4. Make gws-axi your agent's default for Google Workspace
 
-On first invocation (which already happened during step 2), `gws-axi` auto-installed a **SessionStart hook** into your agent's config (Claude Code's `~/.claude/settings.json`, Codex's `~/.codex/hooks.json`). From now on, every new agent session will see a compact `gws-axi` status line in ambient context — authenticated accounts, write-protection status, setup health — with no extra wiring. Nothing for you to configure.
+gws-axi gives agents two complementary ways to pick up ambient context (per [AXI principle 7](https://axi.md) — context is delivered through hooks and installable skills, and installation is always explicit opt-in, never a side effect of ordinary commands):
+
+```bash
+gws-axi setup hooks
+```
+
+This installs a **SessionStart hook** into your agent's config — Claude Code (`~/.claude/settings.json`), Codex (`~/.codex/hooks.json`), and OpenCode. From then on, every new agent session sees a compact `gws-axi` status line in ambient context — authenticated accounts, write-protection status, setup health. The command is idempotent and self-repairing: re-run it any time (e.g. after upgrading or moving the install) and it repairs a stale executable path without duplicating entries. There is no auto-install — the hook only appears when you run `setup hooks`.
+
+The hook and an installable skill are the two ambient-context paths: the hook injects current state at session start, while a skill can teach the agent the full command surface on demand. Run `gws-axi setup hooks` to get the hook in place.
 
 To make sure agents reach for `gws-axi` instead of stale alternatives, also consider:
 

package/dist/src/cli.d.ts

@@ -1,2 +1,2 @@
-export declare const TOP_HELP = "usage: gws-axi [command] [args] [flags]\ncommands[8]:\n  (none)=home, auth, doctor, calendar, gmail, docs, drive, slides\nflags[2]:\n  --help, -v/-V/--version\nexamples:\n  gws-axi\n  gws-axi auth setup\n  gws-axi doctor\n  gws-axi calendar events\n";
+export declare const TOP_HELP = "usage: gws-axi [command] [args] [flags]\ncommands[9]:\n  (none)=home, auth, doctor, calendar, gmail, docs, drive, slides, setup\nflags[2]:\n  --help, -v/-V/--version\nexamples:\n  gws-axi\n  gws-axi auth setup\n  gws-axi doctor\n  gws-axi calendar events\n  gws-axi setup hooks\n";
 export declare function main(): Promise<void>;

package/dist/src/cli.js

@@ -10,11 +10,12 @@ import { gmailCommand } from "./commands/gmail.js";
 import { docsCommand } from "./commands/docs.js";
 import { driveCommand } from "./commands/drive.js";
 import { slidesCommand } from "./commands/slides.js";
+import { setupCommand, SETUP_HELP } from "./commands/setup.js";
 const DESCRIPTION = "Agent ergonomic CLI for Google Workspace. Unified interface for Gmail, Calendar, Docs, Drive, and Slides with agent-guided OAuth setup.";
 const VERSION = readPackageVersion();
 export const TOP_HELP = `usage: gws-axi [command] [args] [flags]
-commands[8]:
-  (none)=home, auth, doctor, calendar, gmail, docs, drive, slides
+commands[9]:
+  (none)=home, auth, doctor, calendar, gmail, docs, drive, slides, setup
 flags[2]:
   --help, -v/-V/--version
 examples:
@@ -22,6 +23,7 @@ examples:
   gws-axi auth setup
   gws-axi doctor
   gws-axi calendar events
+  gws-axi setup hooks
 `;
 // Services that have real subcommand dispatchers handle --help themselves
 // (so `<service> <sub> --help` shows subcommand-specific help). For stubs
@@ -29,13 +31,13 @@ examples:
 const COMMAND_HELP = {
     auth: AUTH_HELP,
     doctor: DOCTOR_HELP,
+    setup: SETUP_HELP,
 };
 export async function main() {
     await runAxiCli({
         description: DESCRIPTION,
         version: VERSION,
         topLevelHelp: TOP_HELP,
-        ...(process.env.GWS_AXI_DISABLE_HOOKS === "1" ? { hooks: false } : {}),
         home: async () => homeCommand(),
         commands: {
             auth: authCommand,
@@ -45,6 +47,7 @@ export async function main() {
             docs: docsCommand,
             drive: driveCommand,
             slides: slidesCommand,
+            setup: setupCommand,
         },
         getCommandHelp: (command) => COMMAND_HELP[command],
     });

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,MAAM,WAAW,GACf,yIAAyI,CAAC;AAE5I,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;AAErC,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;CAUvB,CAAC;AAEF,0EAA0E;AAC1E,0EAA0E;AAC1E,iEAAiE;AACjE,MAAM,YAAY,GAA2B;IAC3C,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,WAAW;CACpB,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,SAAS,CAAC;QACd,WAAW,EAAE,WAAW;QACxB,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE,QAAQ;QACtB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,WAAW,EAAE;QAC/B,QAAQ,EAAE;YACR,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,aAAa;YACrB,QAAQ,EAAE,eAAe;YACzB,KAAK,EAAE,YAAY;YACnB,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,aAAa;SACtB;QACD,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC;KACnD,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAErD,KAAK,MAAM,SAAS,IAAI;QACtB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;QAChC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;KACvC,EAAE,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAEzD,CAAC;QACF,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpE,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE/D,MAAM,WAAW,GACf,yIAAyI,CAAC;AAE5I,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;AAErC,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;CAWvB,CAAC;AAEF,0EAA0E;AAC1E,0EAA0E;AAC1E,iEAAiE;AACjE,MAAM,YAAY,GAA2B;IAC3C,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,WAAW;IACnB,KAAK,EAAE,UAAU;CAClB,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,SAAS,CAAC;QACd,WAAW,EAAE,WAAW;QACxB,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE,QAAQ;QACtB,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,WAAW,EAAE;QAC/B,QAAQ,EAAE;YACR,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,aAAa;YACrB,QAAQ,EAAE,eAAe;YACzB,KAAK,EAAE,YAAY;YACnB,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,aAAa;YACrB,KAAK,EAAE,YAAY;SACpB;QACD,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC;KACnD,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAErD,KAAK,MAAM,SAAS,IAAI;QACtB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;QAChC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;KACvC,EAAE,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAEzD,CAAC;QACF,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpE,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;AACjE,CAAC"}

package/dist/src/commands/setup.d.ts

@@ -0,0 +1,2 @@
+export declare const SETUP_HELP = "usage: gws-axi setup hooks\nInstall or repair agent SessionStart hooks so each session starts with gws-axi's\nhome view (Google Workspace state \u2014 authenticated accounts, write-protection status,\nsetup/health) as ambient context. Installs to Claude Code, Codex, and OpenCode.\nIdempotent; repairs a stale executable path.\nexamples:\n  gws-axi setup hooks";
+export declare function setupCommand(args: string[]): Promise<string>;

package/dist/src/commands/setup.js

@@ -0,0 +1,25 @@
+import { AxiError, installSessionStartHooks } from "axi-sdk-js";
+import { joinBlocks, renderHelp, renderObject } from "../output/index.js";
+export const SETUP_HELP = `usage: gws-axi setup hooks
+Install or repair agent SessionStart hooks so each session starts with gws-axi's
+home view (Google Workspace state — authenticated accounts, write-protection status,
+setup/health) as ambient context. Installs to Claude Code, Codex, and OpenCode.
+Idempotent; repairs a stale executable path.
+examples:
+  gws-axi setup hooks`;
+export async function setupCommand(args) {
+    if (args.includes("--help"))
+        return SETUP_HELP;
+    if (args[0] !== "hooks") {
+        throw new AxiError(`Unknown setup action: ${args[0] ?? "(none)"}`, "VALIDATION_ERROR", [
+            "Run `gws-axi setup hooks`",
+        ]);
+    }
+    const errors = [];
+    installSessionStartHooks({ marker: "gws-axi", timeoutSeconds: 10, onError: (m) => errors.push(m) });
+    if (errors.length > 0) {
+        throw new AxiError("Hook installation reported problems", "HOOK_INSTALL_FAILED", errors);
+    }
+    return joinBlocks(renderObject({ hooks: { status: "installed", integrations: "Claude Code, Codex, OpenCode", marker: "gws-axi" } }), renderHelp(["Restart your agent session to receive gws-axi ambient context"]));
+}
+//# sourceMappingURL=setup.js.map

package/dist/src/commands/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/commands/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE1E,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;sBAMJ,CAAC;AAEvB,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAc;IAC/C,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,UAAU,CAAC;IAC/C,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAAC,yBAAyB,IAAI,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,EAAE,kBAAkB,EAAE;YACrF,2BAA2B;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,wBAAwB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpG,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,QAAQ,CAAC,qCAAqC,EAAE,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC3F,CAAC;IAED,OAAO,UAAU,CACf,YAAY,CAAC,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,8BAA8B,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC,EACjH,UAAU,CAAC,CAAC,+DAA+D,CAAC,CAAC,CAC9E,CAAC;AACJ,CAAC"}

package/dist/src/commands/setup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/commands/setup.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { AxiError } from "axi-sdk-js";
+import { setupCommand, SETUP_HELP } from "./setup.js";
+describe("setup command", () => {
+    it("returns help for --help without installing", async () => {
+        await expect(setupCommand(["--help"])).resolves.toBe(SETUP_HELP);
+    });
+    it("rejects an unknown action with VALIDATION_ERROR", async () => {
+        await expect(setupCommand(["frobnicate"])).rejects.toMatchObject({
+            code: "VALIDATION_ERROR",
+        });
+    });
+    it("rejects a missing action with VALIDATION_ERROR (AxiError)", async () => {
+        try {
+            await setupCommand([]);
+            throw new Error("should have thrown");
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(AxiError);
+            expect(err.code).toBe("VALIDATION_ERROR");
+        }
+    });
+    it("SETUP_HELP documents the single `setup hooks` action", () => {
+        expect(SETUP_HELP).toContain("gws-axi setup hooks");
+    });
+});
+//# sourceMappingURL=setup.test.js.map

package/dist/src/commands/setup.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.test.js","sourceRoot":"","sources":["../../../src/commands/setup.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtD,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;QAC/D,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;YAC/D,IAAI,EAAE,kBAAkB;SACzB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,EAAE,CAAC,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;YACrC,MAAM,CAAE,GAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gws-axi",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "AXI-compliant Google Workspace CLI — token-efficient TOON output, agent-guided auth setup, unified interface for Gmail, Calendar, Docs, Drive, Slides",
   "type": "module",
   "repository": {