@hasna/recordings 0.1.3 → 0.1.6

package/LICENSE

@@ -1,21 +1,170 @@
-MIT License
-
-Copyright (c) 2026 Hasna
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+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 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, as submitted to the 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 recording and
+discussing the Work, but excluding communication that is conspicuously
+marked or designated in writing by the copyright owner as "Not a
+Contribution."
+
+"Contributor" shall mean Licensor and any Legal Entity on behalf of
+whom a Contribution has been received by the Licensor and included
+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 contributions
+Licensors can make available under this License.
+
+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, You must include a readable copy of the attribution
+notices contained within such NOTICE file, 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 license statement for Your modifications and
+may provide additional grant of rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software.
+
+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 exemplary 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 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 offer only
+conditions consistent with this License.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2024 hasna.com
+
+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/dist/mcp/index.js

@@ -4190,6 +4190,12 @@ var MIGRATIONS = [
   CREATE INDEX IF NOT EXISTS idx_recordings_created ON recordings(created_at);
   CREATE INDEX IF NOT EXISTS idx_recordings_mode ON recordings(processing_mode);
   CREATE INDEX IF NOT EXISTS idx_recording_tags_tag ON recording_tags(tag);
+  `,
+  `
+  ALTER TABLE recordings ADD COLUMN goal TEXT;
+  ALTER TABLE recordings ADD COLUMN role TEXT;
+  ALTER TABLE recordings ADD COLUMN task_list_id TEXT;
+  INSERT OR IGNORE INTO _migrations (id) VALUES (2);
   `
 ];
 function getDatabase(dbPath) {
@@ -4239,6 +4245,9 @@ function parseRow(row) {
     agent_id: row["agent_id"] || null,
     project_id: row["project_id"] || null,
     session_id: row["session_id"] || null,
+    goal: row["goal"] || null,
+    role: row["role"] || null,
+    task_list_id: row["task_list_id"] || null,
     metadata: JSON.parse(row["metadata"] || "{}"),
     created_at: row["created_at"]
   };
@@ -4248,8 +4257,8 @@ function createRecording(input, db) {
   const id = crypto.randomUUID();
   const tagsJson = JSON.stringify(input.tags || []);
   const metadataJson = JSON.stringify(input.metadata || {});
-  d.query(`INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, metadata)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.audio_path || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-mini-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, tagsJson, input.agent_id || null, input.project_id || null, input.session_id || null, metadataJson);
+  d.query(`INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.audio_path || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-mini-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, tagsJson, input.agent_id || null, input.project_id || null, input.session_id || null, input.goal || null, input.role || null, input.task_list_id || null, metadataJson);
   if (input.tags && input.tags.length > 0) {
     const insertTag = d.query("INSERT OR IGNORE INTO recording_tags (recording_id, tag) VALUES (?, ?)");
     for (const tag of input.tags) {
@@ -4700,6 +4709,9 @@ server.tool("save_recording", "Save text as recording. Auto-enhances if needed."
   agent_id: exports_external.string().optional(),
   project_id: exports_external.string().optional(),
   session_id: exports_external.string().optional(),
+  goal: exports_external.string().optional().describe("Goal or purpose of this recording session (e.g. 'code review for PR #123')"),
+  role: exports_external.string().optional().describe("Agent role for this session (e.g. 'dev agent for connectdev')"),
+  task_list_id: exports_external.string().optional().describe("Task list ID to bind this recording to"),
   metadata: exports_external.record(exports_external.unknown()).optional()
 }, async (args) => {
   try {
@@ -4724,6 +4736,9 @@ server.tool("save_recording", "Save text as recording. Auto-enhances if needed."
       agent_id: args.agent_id,
       project_id: args.project_id,
       session_id: args.session_id,
+      goal: args.goal,
+      role: args.role,
+      task_list_id: args.task_list_id,
       metadata: args.metadata
     });
     const output = processedText || args.text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/recordings",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "type": "module",
   "description": "Speech-to-text recording tool with MCP and CLI — records, transcribes, and optionally enhances text using AI",
   "main": "dist/index.js",
@@ -38,9 +38,9 @@
     "typescript": "^5.8.2"
   },
   "publishConfig": {
-    "access": "restricted",
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": "Hasna <andrei@hasna.com>"
 }

package/src/db/database.ts

@@ -63,6 +63,14 @@ const MIGRATIONS = [
   CREATE INDEX IF NOT EXISTS idx_recordings_mode ON recordings(processing_mode);
   CREATE INDEX IF NOT EXISTS idx_recording_tags_tag ON recording_tags(tag);
   `,
+
+  // Migration 2: session tagging attributes
+  `
+  ALTER TABLE recordings ADD COLUMN goal TEXT;
+  ALTER TABLE recordings ADD COLUMN role TEXT;
+  ALTER TABLE recordings ADD COLUMN task_list_id TEXT;
+  INSERT OR IGNORE INTO _migrations (id) VALUES (2);
+  `,
 ];
 
 export function getDatabase(dbPath?: string): Database {

package/src/db/recordings.ts

@@ -22,6 +22,9 @@ function parseRow(row: Record<string, unknown>): Recording {
     agent_id: (row["agent_id"] as string) || null,
     project_id: (row["project_id"] as string) || null,
     session_id: (row["session_id"] as string) || null,
+    goal: (row["goal"] as string) || null,
+    role: (row["role"] as string) || null,
+    task_list_id: (row["task_list_id"] as string) || null,
     metadata: JSON.parse((row["metadata"] as string) || "{}") as Record<string, unknown>,
     created_at: row["created_at"] as string,
   };
@@ -37,8 +40,8 @@ export function createRecording(
   const metadataJson = JSON.stringify(input.metadata || {});
 
   d.query(
-    `INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, metadata)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    `INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
   ).run(
     id,
     input.audio_path || null,
@@ -53,6 +56,9 @@ export function createRecording(
     input.agent_id || null,
     input.project_id || null,
     input.session_id || null,
+    input.goal || null,
+    input.role || null,
+    input.task_list_id || null,
     metadataJson
   );
 

package/src/mcp/index.ts

@@ -152,6 +152,9 @@ server.tool(
     agent_id: z.string().optional(),
     project_id: z.string().optional(),
     session_id: z.string().optional(),
+    goal: z.string().optional().describe("Goal or purpose of this recording session (e.g. 'code review for PR #123')"),
+    role: z.string().optional().describe("Agent role for this session (e.g. 'dev agent for connectdev')"),
+    task_list_id: z.string().optional().describe("Task list ID to bind this recording to"),
     metadata: z.record(z.unknown()).optional(),
   },
   async (args) => {
@@ -179,6 +182,9 @@ server.tool(
         agent_id: args.agent_id,
         project_id: args.project_id,
         session_id: args.session_id,
+        goal: args.goal,
+        role: args.role,
+        task_list_id: args.task_list_id,
         metadata: args.metadata,
       });
 

package/src/native/Recordings/Package.resolved

@@ -0,0 +1,15 @@
+{
+  "originHash" : "a6c896b6f831f2130914352c7417e95b036b1f02a1ff70318f1f4e5aa8966e9b",
+  "pins" : [
+    {
+      "identity" : "keyboardshortcuts",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/sindresorhus/KeyboardShortcuts",
+      "state" : {
+        "revision" : "1aef85578fdd4f9eaeeb8d53b7b4fc31bf08fe27",
+        "version" : "2.4.0"
+      }
+    }
+  ],
+  "version" : 3
+}

package/src/native/Recordings/Package.swift

@@ -0,0 +1,21 @@
+// swift-tools-version: 6.2
+
+import PackageDescription
+
+let package = Package(
+    name: "Recordings",
+    platforms: [
+        .macOS(.v26)
+    ],
+    dependencies: [
+        .package(url: "https://github.com/sindresorhus/KeyboardShortcuts", from: "2.0.0")
+    ],
+    targets: [
+        .executableTarget(
+            name: "Recordings",
+            dependencies: ["KeyboardShortcuts"],
+            path: "Recordings",
+            exclude: ["Info.plist", "Recordings.entitlements"]
+        )
+    ]
+)

package/src/native/Recordings/Recordings/FnKeyMonitor.swift

@@ -0,0 +1,122 @@
+import Cocoa
+
+/// Monitors the fn/Globe key using CGEventTap.
+/// Based on the proven pattern from CustomWispr (open-source WisprFlow alternative).
+/// User must set System Settings > Keyboard > "Press fn key to: Do Nothing" for this to work.
+final class FnKeyMonitor: @unchecked Sendable {
+    var onFnKeyDown: (() -> Void)?
+    var onFnKeyUp: (() -> Void)?
+
+    private var eventTap: CFMachPort?
+    private var runLoopSource: CFRunLoopSource?
+    private var healthCheckTimer: Timer?
+    private var fnIsDown = false
+
+    private static let fnKeyCode: UInt16 = 63
+    private static let fnFlagMask: UInt64 = 0x800000
+
+    /// Start monitoring. Returns true if successful.
+    func start() -> Bool {
+        guard eventTap == nil else {
+            fputs("[FnKeyMonitor] Already running\n", stderr)
+            return true
+        }
+
+        fputs("[FnKeyMonitor] Creating event tap...\n", stderr)
+        let eventMask: CGEventMask = (1 << CGEventType.flagsChanged.rawValue)
+
+        // passRetained so the callback reference stays alive
+        let selfPtr = Unmanaged.passRetained(self).toOpaque()
+
+        guard let tap = CGEvent.tapCreate(
+            tap: .cgSessionEventTap,
+            place: .headInsertEventTap,
+            options: .defaultTap,
+            eventsOfInterest: eventMask,
+            callback: { (proxy, type, event, refcon) -> Unmanaged<CGEvent>? in
+                guard let refcon = refcon else { return Unmanaged.passRetained(event) }
+                let monitor = Unmanaged<FnKeyMonitor>.fromOpaque(refcon).takeUnretainedValue()
+                return monitor.handleEvent(type: type, event: event)
+            },
+            userInfo: selfPtr
+        ) else {
+            Unmanaged<FnKeyMonitor>.fromOpaque(selfPtr).release()
+            return false
+        }
+
+        self.eventTap = tap
+
+        let source = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, tap, 0)
+        self.runLoopSource = source
+        CFRunLoopAddSource(CFRunLoopGetCurrent(), source, .commonModes)
+        CGEvent.tapEnable(tap: tap, enable: true)
+        fputs("[FnKeyMonitor] Event tap created and enabled OK\n", stderr)
+
+        // Health check: macOS silently disables taps — re-enable every 3 seconds
+        healthCheckTimer = Timer.scheduledTimer(withTimeInterval: 3.0, repeats: true) { [weak self] _ in
+            guard let self = self, let tap = self.eventTap else { return }
+            if !CGEvent.tapIsEnabled(tap: tap) {
+                fputs("[FnKeyMonitor] Tap was disabled, re-enabling\n", stderr)
+                CGEvent.tapEnable(tap: tap, enable: true)
+            }
+        }
+
+        return true
+    }
+
+    func stop() {
+        healthCheckTimer?.invalidate()
+        healthCheckTimer = nil
+
+        if let tap = eventTap {
+            CGEvent.tapEnable(tap: tap, enable: false)
+        }
+        if let source = runLoopSource {
+            CFRunLoopRemoveSource(CFRunLoopGetCurrent(), source, .commonModes)
+        }
+        eventTap = nil
+        runLoopSource = nil
+        fnIsDown = false
+    }
+
+    private func handleEvent(type: CGEventType, event: CGEvent) -> Unmanaged<CGEvent>? {
+        // Re-enable if macOS disabled the tap
+        if type == .tapDisabledByTimeout || type == .tapDisabledByUserInput {
+            if let tap = eventTap {
+                CGEvent.tapEnable(tap: tap, enable: true)
+            }
+            return Unmanaged.passRetained(event)
+        }
+
+        let keyCode = UInt16(event.getIntegerValueField(.keyboardEventKeycode))
+
+        // Only handle fn key (keyCode 63)
+        guard keyCode == FnKeyMonitor.fnKeyCode else {
+            return Unmanaged.passRetained(event)
+        }
+
+        let flags = event.flags.rawValue
+        let fnPressed = (flags & FnKeyMonitor.fnFlagMask) != 0
+
+        fputs("[FnKeyMonitor] flagsChanged keyCode=\(keyCode) flags=0x\(String(flags, radix: 16)) fnPressed=\(fnPressed) fnIsDown=\(fnIsDown)\n", stderr)
+
+        if fnPressed && !fnIsDown {
+            // fn just pressed
+            fnIsDown = true
+            fputs("[FnKeyMonitor] fn DOWN — starting recording\n", stderr)
+            DispatchQueue.main.async { [weak self] in
+                self?.onFnKeyDown?()
+            }
+            return nil // Swallow — prevents emoji picker / language switch
+        } else if !fnPressed && fnIsDown {
+            // fn released
+            fnIsDown = false
+            DispatchQueue.main.async { [weak self] in
+                self?.onFnKeyUp?()
+            }
+            return nil // Swallow release too
+        }
+
+        return Unmanaged.passRetained(event)
+    }
+}

package/src/native/Recordings/Recordings/Info.plist

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>LSUIElement</key>
+    <true/>
+    <key>CFBundleName</key>
+    <string>Recordings</string>
+    <key>CFBundleDisplayName</key>
+    <string>Recordings</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.hasna.recordings</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.1.0</string>
+    <key>LSMinimumSystemVersion</key>
+    <string>26.0</string>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>Recordings needs microphone access to record and transcribe your speech.</string>
+</dict>
+</plist>